Dynamics AX Retail Online Store

Table Of Contents
Chapter 1
Install an online store (e-commerce)
Install multiple online stores
Set up and configure an online store
Bulk edit attributes in Microsoft Excel
Getting started with customizing the Retail online sample store
Architecture of the online store
Online store publishing architecture
Plan for an online store
Quick Guide: How to customize an online store
Set up and configure refiners
Customize master pages
Customize page layouts
Customize the appearance and behavior of site pages
Cascading style sheet (CSS) files for Retail online store
Customize the functionality of an online store
Customize display templates for an online store
Debug X++ Code for Retail
Debug code in a Retail online sample store
Update the Publishing Job Configuration
Create a URL for search engine optimization (SEO) in a Retail online store
Components of the Retail online sample store
Authenticating users in Retail online sample stores
Walkthrough: Extending the database schema
Walkthrough: Extending the Retail online sample store
Walkthrough: Adding Properties to a Sales Order
Retail online sample store reference
Install a Retail online store (e-commerce) [AX 2012]

Updated: November 20, 2014
Applies To: Microsoft Dynamics AX 2012 R3, Microsoft Dynamics AX 2012 R2
This topic describes how to install a Microsoft Dynamics AX Retail online store. The Retail online store is also called the Microsoft Dynamics AX e-commerce store. This topic includes procedures for
single server and server farm deployments. You can install the online store by using Setup.exe or by using Windows PowerShell scripts. Both options are described in this topic. After you complete the
installation procedures described in this topic, a starter store is deployed in your computing environment. You can then configure, customize, and rebrand the starter store to meet your needs.
This topic includes the following sections.
Before you begin

Install the Retail online store by using Setup
Deploy the Retail online store by using Windows PowerShell
Next steps for developers
Uninstall an online store
Before you begin

You must complete the following tasks before you deploy the Microsoft Dynamics AX Retail online store.
Task
Verify that your computing
environment meets all system
requirements
Details
Verify that the SharePoint server(s) that will host the Retail online store meet the following requirements: 16 GB of RAM recommended; 10 GB of
RAM and 4 processors, minimum.
Verify that the SQL server is not running SQL Express. The retail online store is not supported with SQL Express.
For more information about system requirements, see Hardware and software requirements.
Install URL Rewrite
Verify that you installed the URL Rewrite Module 2.0 (64-bit) on each SharePoint server.
Deploy and configure SharePoint

Deploy and configure SharePoint Server 2013 Service Pack 1 or later (Enterprise edition). For more information, see Overview of SharePoint 2013
installation and configuration
Download and install all cumulative updates for SharePoint Server 2013. To improve update installation times, use the PowerShell script described
in this MSDN blog.
Verify that Microsoft Dynamics AX and

all updates are installed in your
computing environment
Verify that Microsoft Dynamics AX

Retail features are installed in your
computing environment
Install Microsoft Dynamics AX 2012

Apply updates and hotfixes
You must install the following Retail features:
Retail headquarters
Commerce Data Exchange components
Retail SDK
Retail channel database
For more information, see Install retail components
Prepare the developer environment
Set up the development environment for a Retail online store
Verify that SharePoint application

pools are running in IIS
Verify that all SharePoint application pools are running in IIS Manager.
Important
If the SharePoint Web Services Root application pool is stopped, you must start it.
Verify that required SharePoint services

are running
In SharePoint Central Administration, click Application Management > Service Applications > Manage Services on Server and verify that, at a
minimum, the following services are running:
Central Administration
Managed Metadata Web Service
Microsoft SharePoint Foundation Workflow Timer Service
Microsoft SharePoint Foundation Web Application
Search Host Controller Service
Search Query and Site Settings Service
SharePoint Server Search
Verify role requirements

If you did not install and configure Microsoft Dynamics AX, verify that you are a member of the system administrator role in Microsoft Dynamics
AX.
If you did not install and configure SharePoint, verify that you are a member of the farm administrator role in SharePoint and that you have
administrator access to each site collection in the farm.
If you did not install and configure Microsoft SQL Server, Microsoft Dynamics AX, or SharePoint, verify that you are a member of the sysadmin
role on the Microsoft Dynamics AX databases and all SharePoint databases.
Create domain user accounts
Verify or create the following domain accounts. You will specify these accounts when you deploy the Retail online store later in this topic.
Product Catalog Web App Pool User: This account must be a member of the SharePoint Farm Administrators group so that it can edit
properties in the root web site. This account will be specified later in this topic.
StoreFront Web App Pool User: This account must be a member of the SharePoint Farm Administrators group so that it can edit properties in
the root web site. This account will be specified later in this topic.
STS Web App Pool User: This account must be a member of the SharePoint Farm Administrators group so that it can edit properties in the root
web site. This account was specified when you installed SharePoint. It is the account under which the Security Token Service application pool runs
in IIS Manager.
Retail Job User: This account was specified when you installed SharePoint. It is the account under which the SharePoint Timer Service runs.
Acquire Secure Sockets Layer (SSL)

certificates
Encryption settings: The Retail store publishing portal uses SSL encryption. For production environments, you must register your domain and obtain a
valid, registered SSL certificate from a provider. For developer and evaluation environments, you can use a self-signed certificate. For information about
how to work with certificates see Certificate Overview.
Verify SQLCMD utility
The SQLCMD utility is required to install the Retail online store. This utility is typically installed with Microsoft SQL Server. If a version of SQL Server is not
installed on the computer where you install the online store, you can download and install Microsoft Command Line Utilities 11 for SQL Server to meet
this requirement.
Verify warehouse requirement
You cannot configure a Microsoft Dynamics AX Retail store (online store or brick-and-mortar store) to use a warehouse that is managed by the
Warehouse Management module. The module was introduced in AX 2012 R3. You can configure a Retail online store to use a warehouse that is
managed by the Inventory Management module.
Verify SharePoint Managed Metadata connection properties

You must verify that the SharePoint Managed Metadata connection required options are enabled.
1. In SharePoint Central Administration, under Application Management, click Manage service applications.
2. Highlight the Managed Metadata Service Connection row and then click Properties.
3. Verify that the following options are selected.
4. Save your changes.

5. If you are installing Microsoft Dynamics AX 2012 R3 Cumulative Update 8, you must also complete the following steps:
a. In Central Administration, under Application Management, click Manage Service Applications.
b. Click Managed Metadata Service.
c. In the Term Store Management tool, add the user name in the Term Store Administrators field. Ensure that the user name is the same as the service account for SharePoint Timer
Service.
d. Click Check Names, and then click Save.
Prepare your developer environment for signing updated source code

After you install the online store as described in this topic, you will be ready to customize the store you deployed. The process of customizing the Retail online store requires that you recompile
the source code in the Visual Studio projects. After you recompile, the fully-qualified name of the rebuilt assemblies will be different than the assemblies originally provide by Microsoft. Before you
can recompile the assemblies, you must provide a code signing key file (also called a strong name key file) to sign the customized code. If your business has a code signing key file (.snk file), you
can reuse this file. If you do not have a code signing key file, Visual Studio can create one for you. You must create a new project and enable code signing. Then, create a second project that
references the .dll of the output of the first project. You can locate the thumbprint in the assembly reference of the .csproj file in the second project. When you have the .snk file, you must do the
following:
1. Save the file in the Retail SDK folder and give it a name Name.snk.
2. Edit the UpdateAssemblyIdentities.ps1 file in the Retail SDK folder. You must update the version number and the thumbprint of the key file (lines 97, 98).
3. Update the source code to use the strong name certificate by executing the UpdateAssemblyIdentities.ps1 script. This script can take several minutes to complete.
Additional steps and recommendations for developers are described in the Next steps for developers section in this topic.
Option 1: Install the Retail online store by using Setup

You can install the Retail online store by using Microsoft Dynamics AX Setup or by using Windows PowerShell scripts. If you prefer to install the Retail online store manually, see Install the Retail
online store by using Windows PowerShell in this topic.
If you install other Microsoft Dynamics AX components at the same time, the installation pages vary, depending on the components that you are installing.
1. Start Microsoft Dynamics AX Setup. Under Install, select Microsoft Dynamics AX components.
2. Advance through the first wizard pages.
3. If the Setup Support files have not yet been installed on this computer, the Select a file location page is displayed. The Setup Support files are required for installation. Provide a file location
or accept the default location, and then click Next. On the Ready to install page, click Install.
4. On the Select installation type page, click Custom installation, and then click Next.
5. On the Select components page, select Retail online channel, and then click Next.
6. On the Prerequisite validation results page, resolve any errors. For more information about how to resolve prerequisite errors, see Check prerequisites. When no errors remain, click Next.
7. On the Configure a Microsoft Dynamics AX Retail online store page, enter the following information about the web site where the online store will run.
On the Configure the Retail online channel page, select the check box to configure online store by using Setup. If you clear this option, the application files are installed, but the
online store is not deployed or configured.
If youre configuring the online store, enter the following information:
Storefront to deploy: Select a Retail starter store to deploy. The Contoso starter store is modeled after an online electronics retailer. The Fabrikam starter store is modeled after an
online clothing retailer.
Database server: The name of the server that will host the Retail online store databases
Channel database name: The name of the Retail channel database. If this database does not exist, you must cancel Setup and install a Retail channel database.
User name and Password: The credentials for a domain account that has permission to create web applications and execute PowerShell scripts in SharePoint.
Pfx file path: The path to the Pfx file for the SSL certificate.
Password: The password for the Pfx file.
Channel operating unit number: A channel operating unit number is specified when you create an online channel in the Microsoft Dynamics AX client. You must create the channel
before you deploy the Retail online store. To locate this operating unit number, click Retail > Retail channels > Online Stores.
8. On the Prerequisite validation results page, resolve any errors. For more information about how to resolve prerequisite errors, see Check prerequisites. When no errors remain, click Next.
9. On the Ready to install page, click Install.
10. After the installation is completed, click Finish to close the wizard.
If the deployment succeeded, proceed to the Verify deployment section in this document. If the deployment failed check the Microsoft Dynamics AX log file and the Windows event logs for
information. For additional troubleshooting support, see the Troubleshooting deployment issues section in Troubleshoot installation issues for a Retail online store.
Option 2: Deploy the Retail online store by using Windows PowerShell

Use this procedure to install the Retail online store manually by using Windows PowerShell. Manual installations are often performed by businesses and organizations that automate deployments by
using scripts.
Extract installation files

Use Microsoft Dynamics AX Setup to extract the files that are needed for manual installation. Perform this procedure on the SharePoint server that will host the online store.
1. Start Microsoft Dynamics AX Setup. Under Install, select Microsoft Dynamics AX components.
2. Advance through the first wizard pages.
3. If the Setup Support files have not yet been installed on this computer, the Select a file location page is displayed. The Setup Support files are required for installation. Provide a file
location or accept the default location, and then click Next. On the Ready to install page, click Install.
4. On the Select installation type page, click Custom installation, and then click Next.
5. On the Select components page, select Retail online channel, and then click Next.
6. On the Prerequisite validation results page, resolve any errors. For more information about how to resolve prerequisite errors, see Check prerequisites. When no errors remain, click
Next.
7. On the Configure a Microsoft Dynamics AX Retail online store page, clear the Configure Retail online store option. Click Next.
8. On the Prerequisite validation results page, resolve any errors. For more information about how to resolve prerequisite errors, see Check prerequisites. When no errors remain, click
Next.
9. On the Ready to install page, click Install.
10. After the installation is completed, click Finish to close the wizard. Setup extracts files and creates the following folder on the local server:
C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Online Channel
Configure settings in the Retail online store xml file

After you extract the installation files by using Setup, you must configure settings in the oob-settings.xml file.
Before you begin

If you deployed SharePoint on Windows Server 2012, then you must complete the following procedure to ensure that the Microsoft.Web.Administration.dll is not overwritten in the global
assembly cache when you execute deployment scripts later in this topic. You do not need to perform this procedure on Windows Server 2008 R2.
1. Open the manifest.xml file in the following directory on the SharePoint server:
C:\...\Retail Online Channel\StoreFront\SP
2. Delete the following line of code from the manifest.xml file:
<Assembly Location="Microsoft.Web.Administration.dll" DeploymentTarget="GlobalAssemblyCache" />
3. Save and close the file.
The Microsoft.Web.Administration.dll in the global assembly cache will not be overwritten when you execute PowerShell commands later in this topic.
Configure settings in the oob-settings.xml file

This section describes how to configure settings in the oob-settings.xml file.
1. Open the following directory:

C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Online Channel\tools
2. Open the oob-settings.xml file in Microsoft Visual Studio or a text editor, such as Notepad.
3. Enter a value for the following parameters.
Parameter
What to enter
Default
StoreFront_Name
Enter the name of the online store to

deploy. You must enter either Contoso
or Fabrikam.
Contoso
StoreFront_Design
Microsoft Dynamics AX uses this value

to determine which customizations to
apply to the publishing portal. Change
this value if, for example, a developer
creates a new design template.
Default
StoreFront_CountryCode
Enter an ISO country code. This code

displays the country string, for example,
when a customer places an order.
Customers of your site do not see this
code. This value is not published.
USA
StoreFront_CountryName
Enter the name of the country.

Customers of your site do not see this
code. This value is not published.
United States
StoreFront_CurrencyTemplate
Enter a currency template. This template

determines how currency amounts are
displayed in the online store.
${0}
SharepointPackageInstanceIdentifier
Enter any alphanumeric value to uniquely

identify this deployment. This value must
be unique across all Retail online store
deployments in the server farm.
None, but we recommend a value of 1.
StoreFront_ItemAvailabilityThreshold
Enter a threshold value for the number

of items in stock for any product. If the
number of items in stock for a specific
product is below this value, the system
could display a banner to the customer
that lets them know how many items are
left in stock. A developer would need to
customize the store to create a banner.
10
StoreFront_ShoppingCartExpiryTerm
Enter the number of days to retain a

shopping cart. If no value is entered, the
store deletes the shopping cart after 24
hours.
None
StoreFront_LanguageId
Enter a language code identifier (LCID).

This ID must match the language pack
for your SharePoint deployment. For
more information about deploying the
online store in multiple languages, see
Install multiple Microsoft Dynamics AX
Retail online stores.
1033
StoreFront_DeviceChannelsListName
This value is the name of a SharePoint

Design Manager list that stores device
channels. For more information about
device channel lists, see SharePoint 2013
Design Manager device channels. The
Device Channels
name of this value varies based on

locale. For example, if you are deploying
the online store by using the en-US
locale then the name should be Device
Channels. If you are deploying for an
online store for fr-FR (French) locale
then this name should be Canaux des
appareils.
Note
The value of this property and the
value of the previous property
(StoreFront_DeviceChannelsListName)
work together. For example, an enUS online store uses the 1033, Device
Channels values and an fr-FR online
store uses the 1036, Canaux des
appareils values.
LoggingServiceName
The name of the logging service for this

deployment as it appears in SharePoint
Central Administration. You can change
the default string value (Dynamics AX
Retail Logging Service) if you want.
However, we recommend that you do
not change the place holder value
([SharepointPackageInstanceIdentifier])
unless you are a developer and
understand the repercussions of making
a change.
Dynamics AX Retail Logging Service

[SharepointPackageInstanceIdentifier]
LoggingCategoryName
The SharePoint diagnostics logging

category where events for this
deployment will be logged. We
recommend that you do not change the
place holder value
a change.
General Logging [SharepointPackageInstanceIdentifier]
MonitoringEventLogSourceName
For events logged in the Windows NT

Event Viewer, this parameter identifies
the source of the event. You can change
the string value (Dynamics AX Retail
Monitoring) if you want. However, we
recommend that you do not change the
place holder value
a change.
Dynamics AX Retail Monitoring [SharepointPackageInstanceIdentifier]
The port for the public online store

site: You can specify any available port.
40002
-------------------PORTS and URLS

-------------------StoreFrontUrlPort_Public
50002 for the Fabrikam starter store

StoreFrontUrlPort_SSL_Public
The port for the public online store

site for encrypted communications:
You can specify any available port.
40004
The port for the internal online store

site: You can specify any available port.
This URL is only accessed by domain
users with permission to make changes
to the site collection by using SharePoint
site settings. It is not required, but you
can change this port value if you want
the internal online store to use a
different port.
40003
The port for the internal product

catalog site: You can specify any
available port. This URL is only accessed
by domain users with permission to
make changes to the site collection by
using SharePoint site settings. It is not
required, but you can change this port
value if you want the internal product
catalog to use a different port.
40001
ResetSearchIndex
Setting this parameter to true clears the

SharePoint index cache and initiates a
full crawl across the farm.
False
StoreFrontSiteCollectionRootUrl_FormsAuth
The local web address of the Retail

online store (as opposed to a public
http://%COMPUTERNAME%:[StoreFrontUrlPort_Public]
StoreFrontUrlPort_Internal
ProductCatalogUrlPort_Internal
address like www.contoso.com.) Enter a

valid server name and remove the %
signs. We recommend that you do not
change the place holder value
([StoreFrontUrlPort_Public]) unless you
are a developer and understand the
repercussions of making a change.
StoreFrontSiteCollectionRootUrl_WindowsAuth
The local web address of the 40003 site.

Enter a valid server name and remove
the % signs. We recommend that you do
not change the place holder value
([StoreFrontUrlPort_Internal]) unless you
are a developer and understand the
http://%COMPUTERNAME%:[StoreFrontUrlPort_Internal]
StoreFrontSiteCollectionRootUrl_FormsAuth_Public
This is the customer facing URL. For

example with a port 80 site, it could be
http://www.contoso.com. With a port
3000 site it could be
http://www.contoso.com:3000.
http://www.[StoreFront_Name].com:[StoreFrontUrlPort_Public]
StoreFrontSiteCollectionRootUrl_SSL_FormsAuth
The internal URL for the online store

encrypted communications site: Enter
a valid server name and remove the %
signs. We recommend that you do not
change the place holder value
([StoreFrontUrlPort_SSL_Public]) unless
you are a developer and understand the
https://%COMPUTERNAME%:[StoreFrontUrlPort_SSL_Public]
StoreFrontSiteCollectionRootUrl_SSL_FormsAuth_Public
The public URL for the online store

encrypted communications site: The
https site customers use for secure
transactions and processing.
https://www.[StoreFront_Name].com:[StoreFrontUrlPort_SSL_Public]
PublishingPortalRelativePath
This relative path is combined with URLs

specified earlier to create a complete
path for the publishing portal. We
recommend that you do not leave this
blank and use a format similar to
/sites/XYZ. Leaving this field blank
would require customizations to the
oob-topology.xml file, and should be
attempted by advanced users only.
/sites/RetailPublishingPortal
StoreFrontPublicSSLCertThumbprint
The thumbprint for your Secure Sockets

Layer (SSL) encryption certificate. You
must obtain a valid, registered certificate
from a provider.
None
-------------------SSL
--------------------
Because this component uses Secure

Sockets Layer (SSL) encryption, you must
install a server certificate that was issued
by a trusted certification authority. (For
test environments, you can create a selfsigned certificate in IIS.) You will need to
paste the thumbprint for the certificate
into the settings file. To view the
thumbprint in IIS Manager, double-click
the certificate and click the Details tab.
We recommend that you paste the
thumbprint into a text file and remove all
spaces before you paste it into the
settings file.
Caution
A thumbprint can contain hidden
characters at the beginning of the
thumbprint value. You must delete
these extra characters before you
paste the thumbprint into the settings
file.
StoreFrontPublicSSLCertDirectory
The source directory where Microsoft

Dynamics AX retrieves the .pfx file for
the SSL certificate. This value can be a
network share.
None
StoreFrontPublicSSLCertLocalDirectory
The destination folder where Microsoft

Dynamics AX stores a local copy of the
certificate. This location cannot be the
same as the
StoreFrontPublicSSLCertDirectory
value.
None
Important
This path cannot contain any special
characters. If the path contains a
special character deployment fails.
StoreFrontPublicSSLCertPfxFileName
Enter the file name and extension. By

default the extension is .pfx.
None
To create a .pfx file for a self-signed

certificate, you must export the
certificate from IIS Manager. To do this,
right-click the certificate, click Export,
and then complete the export wizard.
You must then import the .pfx file into
the local certificate store. Right-click the
.pfx file in the directory where you just
created it, click Import, and then
complete the import wizard.
StoreFrontPublicSSLCertPfxPassword
Enter the password of the .pfx file. This

password cannot contain any restricted
XML characters such as the following:
exclamation point (!), greater than sign
(<), less than sign (>), ampersand (&),
apostrophe , or a quotation mark .
None
StoreFrontWebAppPoolUser
Enter a domain account for the

application pool of the online store.
Enter the account in the form
value="Domain\User". This account
must be a member of the SharePoint
Farm Administrators group because it
must edit properties in the root web
site.
None
ProductCatalogSiteCollectionRootUrl_WindowsAuth
The local web address of the product

catalog. Enter a valid server name and
remove the % signs. We recommend
that you do not change the place holder
value ([ProductCatalogUrlPort_Internal])
a change.
http://%COMPUTERNAME%:[ProductCatalogUrlPort_Internal]
ProductCatalogWebAppPoolUser
Enter a domain account for the

application pool of the catalog site.
Enter the account in the form
value="Domain\User". This account
must be a member of the SharePoint
Farm Administrators group because it
must edit properties in the root web
site.
None
ProductCatalogName
Enter any name for the product catalog.

This value is not displayed to customers.
Retail Product Catalog
STSWebAppPoolUser
This account must be a member of the

SharePoint Farm Administrators group.
Also, this is the domain account used by
the Security Token Service Application
Pool. You specified this account when
you installed SharePoint. To locate the
account in IIS Manager, click
Application Pools, right-click
SecurityTokenServiceApplicationPool,
and then click Advanced Settings. The
account for this application pool is listed
under Process Model > Identity. Enter
the account in the form
value="Domain\User".
None
RetailJobUser
This account must be a member of the

SharePoint Farm Administrators group.
Also, this is the account used by the
SharePoint Timer service. You specified
this account when you installed
SharePoint. Enter the account in the form
None
ChannelOperatingUnitNumber
A channel operating unit number is

specified when you create an online
channel in the Microsoft Dynamics AX
client. You must create the channel
before you deploy the Retail online
store. To locate this operating unit
number, click Retail > Retail channels >
Online Stores.
None
-------------------DOMAIN ACCOUNTS and MISCELLANEOUS

--------------------
DestinationId
A value that uniquely identifies an

endpoint to Commerce Runtime (CRT).
This value must be a GUID. If necessary,
create a GUID by using Visual Studio.
None
PublishingConnectorServiceInstanceServers
A comma-separated list of servers

where the Retail online store publishing
job must run. The PowerShell script is
case sensitive. For example,
value="RetailTestOne, RetailTestTwo"
/>.
None
FarmAdministratorAlias
Enter a domain account and alias of a

SharePoint farm administrator. Enter the
account in the form
None
FarmAdministratorEmail
Enter the e-mail address of a SharePoint

farm administrator. Enter the address in
the form
value="Username@ YourDomain .com".
None
SharePointRelyPartyUrl
https://www.[StoreFront_Name].com:[StoreFrontUrlPort_SSL_Public]/_trust/
-------------------DATABASE DETAILS
-------------------ChannelDatabaseServerName
If you have not already done so, use

Microsoft Dynamics AX Setup.exe to
deploy a Retail channel database. For
this parameter, enter the server name.
The PowerShell script is case sensitive.
For example, value="RetailTestOne"
/>.
None
ChannelDatabaseServerNamedInstanceName
If you installed the retail channel

database as part of a SQL named
instance, enter the named instance. This
parameter cannot be empty. The format
for a SQL instance name is either the
server name or the full instance name.
For example, valid names are:
"localhost", "localhost\instance2",
"server1", "server1\instance2".
None
ChannelDatabaseName
If you have not already done so, use

Microsoft Dynamics AX Setup.exe to
deploy a Retail channel database. For
this parameter, enter the database
name.
None
IdentityProviderDatabaseServerName
The identity provider database is used

for authentication and authorization of
online store registered users. If there
are multiple Retail online store
deployments in the same farm, then the
IdentityProviderDatabase and
CustomClaimsProviderDatabase must be
the same for all Retail online store
deployments in the farm. Enter a server
name. The PowerShell script is case
sensitive. For example,
value="RetailTestOne" />.
None
IdentityProviderDatabaseServerNamedInstanceName
If you installed the identity provider

database as part of a SQL named
instance, enter the named instance. This
parameter cannot be empty. The format
for a SQL instance name is either the
server name or the full instance name.
For example, valid names are:
"localhost", "localhost\instance2",
"server1", "server1\instance2".
None
CustomClaimsProviderDatabaseServerName
The custom claims provider database is

used for authentication and
authorization of online store registered
users. If there are multiple Retail online
store deployments in the same farm,
then the IdentityProviderDatabase and
CustomClaimsProviderDatabase must be
the same for all Retail online store
deployments in the farm. Enter a server
name. The PowerShell script is case
sensitive. For example,
value="RetailTestOne" />.
None
CustomClaimsProviderDatabaseServerNamedInstanceName
If you installed the custom claims

provider database as part of a SQL
named instance, enter the named
instance. You can leave this parameter
None
empty if the database is not part of a

named instance.
BingMapsId
If you want your Retail online store to

work with Bing Maps, then you must
register with Bing Maps. Specify the Bing
Maps ID here.
None
ShowDebugErrorMessages
For a testing environment, set this value

to True to see detailed error messages
in the online store. For production sites
set the value to False.
None
Important
To keep a record of the settings and parameters you specified, we recommend that you make a copy of the oob-settings.xml file after you finished entering parameters.
Configure Facebook integration

The Retail online store can authenticate users who sign in to your site by using their Facebook credentials. This section describes how to configure your environment for Facebook
authentication.
Important
Facebook integration is optional. However, if you do not want to use Facebook authentication, then you must disable this feature in the oob-topology.xml file. If you do not disable it, the
deployment scripts fail. For more information, see Disable Facebook integration later in this topic.
Create a Facebook application: Use the following procedure to create a Facebook application that enables Facebook logon to your site.
1. Logon to the Facebook developer site

2. Register as a developer on the Facebook developer site.
3. Click Create New App and then follow the prompts to create a new application.
4. In the Select how your application integrates with Facebook section, click the Website with Facebook Login option and specify the Site URL.
5. Click Save Changes.
6. On the applications landing page, select the application that you just created.
7. In the oob-settings.xml file, search for FacebookApplicationId. Replace the value with the Facebook ID. Retain the quotation marks.
8. In the oob-settings.xml file, search for FacebookApplicationSecret. Replace the value with the secret you created for your Facebook application. Retain the quotation marks.
9. Save your changes in the oob-settings.xml file.
Certificates: Use the following procedure to create certificates for Facebook authentication. For production environments, you must register your domain and obtain a valid, registered SSL
certificate from a provider. For developer and evaluation environments, you can use a self-signed certificate. For information about how to work with certificates see Certificate Overview.
1. Search in the oobsettings.xml file for the parameters listed in the following table. Enter a value for each parameter. For each value, retain quotation marks but remove percent
signs (%).
Parameter
What to enter
FacebookApplicationId
The ID created when you registered a Facebook application.
FacebookApplicationSecret
The secret specified when you registered a Facebook application.
FacebookCertificateDirectory
The source directory where Microsoft Dynamics AX retrieves the .pfx file for the SSL certificate. This value can be a network share.
FacebookCertificateLocalCopyDirectory
The destination folder where Microsoft Dynamics AX stores a local copy of the certificate. This location cannot be the same as the
StoreFrontPublicSSLCertDirectory value.
FacebookSigningCertificateCerFileName
Enter a value with the name of the certificate .cer file in the form value=" CertificateName .cer".
FacebookSigningCertificatePfxFileName
Enter a value with the name of the certificate .pfx file in the form value=" CertificateName .pfx".
FacebookSigningCertificatePfxPassword
This is a password for a test certificate. For production environments, do not enter a password here. It will be prompted during
deployment. This password cannot contain any restricted XML characters such as the following: exclamation point (!), greater than
sign <, less than sign >, ampersand &, apostrophe , or a quotation mark .
FacebookSigningCertificateThumbprint
The thumbprint for your Secure Sockets Layer (SSL) encryption certificate. You must obtain a valid, registered certificate from a
provider.
Because this component uses Secure Sockets Layer (SSL) encryption, you must install a server certificate that was issued by a
trusted certification authority. (For test environments, you can create a self-signed certificate in IIS.) You will need to paste the
thumbprint for the certificate into the settings file. To view the thumbprint in IIS Manager, double-click the certificate and click the
Details tab. We recommend that you paste the thumbprint into a text file and remove all spaces before you paste it into the
settings file.
Caution
A thumbprint can contain hidden characters at the beginning of the thumbprint value. You must delete these extra characters
before you paste the thumbprint into the settings file.
FacebookSignInUrl
The page that will contact Facebook to authenticate users. For example:
http://www.[StoreFront_Name].com:[StoreFrontUrlPort_Public][PublishingPortalRelativePath]/pages/Login.aspx
FacebookSslCertificateAuthorityCerFileName
Enter the file name.
FacebookSslCertificateAuthorityThumbprint
Enter the thumbprint. Remove all spaces.
2. Save your changes in the oob-settings.xml file.
Note
You can enable Facebook integration in developer environments that are not using a fully registered domain name (for example, www.DomainName.com). To do this, you must create host
file entries on each computer that will browse the online store. The URL for host file entries must be in the form: http://www.DomainName.com/sites/RetailPublishingPortal.
Update the prerequisite script for Facebook

A known issue in this version of the Microsoft Dynamics AX Retail online store can cause an installation to fail if you configure Facebook as an identity provider. If you plan to use Facebook as
an identity provider, perform the following procedure before you install the online store. If you do not plan to use Facebook as an identity provider, you can skip this procedure.
1. Open the following folder:

2. Open the Install-Prerequistes.ps1 file in Microsoft Visual Studio.
3. Search for line 155:
RoboCopy $trustedIdentityTokenIssuerConfig.CertificateDirectory $certificateLocalCopyDirectory
$trustedIdentityTokenIssuerConfig.SigningCertificateCerFileName $trustedIdentityTokenIssuerConfig.SigningCertificatePfxFileName
4. Replace that line with the following:
RoboCopy $trustedIdentityTokenIssuerConfig.CertificateDirectory $certificateLocalCopyDirectory
$trustedIdentityTokenIssuerConfig.SigningCertificateCerFileName $trustedIdentityTokenIssuerConfig.SigningCertificatePfxFileName
$trustedIdentityTokenIssuerConfig.SslCertificateAuthorityCerFileName
Disable Facebook integration

If you do not want to enable Facebook authentication for your Retail online store you must disable it, as described in the following procedure. If you previously enabled and configured
Facebook authentication you can also use this procedure to disable it.
1. Open the oob-topology.xml file in Microsoft Visual Studio or a text editor, such as Notepad.
2. Search in the oobtopology.xml file for the parameter listed in the following table. Enter a value for each parameter. For each value, retain quotation marks but remove percent
signs (%).
Search for
Enter
<TrustedIdentityTokenIssuer id="Facebook" install="true" deleteifexists="true">
Change both flags to false. For example:

<TrustedIdentityTokenIssuer id="Facebook" install="false" deleteifexists="false">
3. Save your changes in the oob-topology.xml file.
Run Windows PowerShell scripts to create and configure the online store
After you configure the parameters in the oob-settings.xml file, you can run the Windows PowerShell scripts that deploy and configure the online store.
In this section, you will execute the following scripts to create and configure the online store.
InstallPrereqs-SPFarm
Generate-WSP
Deploy-FarmSolutions
Toggling options if re-running scripts

If you re-run the PowerShell deployment scripts in this section, by default, existing databases, web applications, features, and settings are deleted. You can, however, toggle different parameters in
the oobtopology.xml file to preserve databases, web applications, features, and settings. Preserving an object means that you change a true flag to false. For example, in the oobtopology
file, in the <Channel> section, the Database is configured as follows.
<Database install="true" dropifexists="true">
By changing each flag to false the deployment scripts preserve the existing databases.
InstallPrereqs-SPFarm.ps1
This script performs the following actions on the server.
Area
Actions
Database actions performed by this script

If you re-run the PowerShell deployment scripts in this section, by default, existing Retail online store databases, web
applications, features, and settings are deleted. You can, however, toggle different parameters in the oob-
Create Windows NT user groups

Add process users to Windows NT user groups
Create SQL Server logins for Windows NT user groups
topology.xml file to preserve databases, web applications, features, and settings, as described earlier in this topic.
SharePoint Server actions performed by this script
Creates trusted identity token issuer for Facebook integration
(on every web front-end server, when executed in a server
farm)
Creates SharePoint web applications
Creates SSL binding (on every web front-end server, when
executed in a server farm)
Creates SharePoint sites
Configures sites and web application properties
Disables versioning of the Retail Online Store Publishing Portal
web application
Configures site URLS (for different zones)
Enables trusted authentication providers for Facebook (if
option was configured)
If you re-run this script, the system performs the following actions
before creating or configuring SharePoint. You can, however, toggle
options to preserve settings, as described earlier in this document.
Deactivates Retail online store features

Removes WSP solution files, if installed
Deletes Retail online store sites
Removes SSL bindings (on every web front-end server, when
executed in a server farm)
Deletes Retail online store web applications
Deletes trusted identity token issuer (on every web front-end
server, when executed in a server farm)
Other actions performed by the script

The script performs the following pre-deployment checks, by default. You can customize which checks are performed.
Verifies that the folders and files referenced in the oobtopology.xml and oob-settings.xml files exist
Verifies that the configured database server can be pinged.
Verifies that the SharePoint server names configured for the
publishing job are correct and that they are joined to the
current SharePoint farm.
Verifies that the SharePoint installation is of the correct
version. SharePoint 2013 is required.
Verifies that every SharePoint server that acts as an application
server has the URL Rewrite module installed.
Verifies that any ports are not already used by web
applications with different names.
If any of these checks fail, the script will not perform the installation.
Run InstallPrereqs-SPFarm.ps1: Use the following procedures to run this script.

Caution
SQL Server work-around for cumulative update 1
Cumulative update 1 has a known issue where the InstallPrereqs-SPFarm.ps1 script fails if SQL Server is not installed on the server where you are running this script. If SQL Server is not
installed on the server and if you do not intend to install any databases, complete the following steps before you run the InstallPrereqs-SPFarm.ps1 script.
1. Open the following folder:

2. Open the Custom-Scripts.ps1 file in Microsoft Visual Studio or a text editor, such as Notepad.
3. Search for and delete the following line of code:
(if((Test-Connection $value -Count 1 -Quiet) -ne $True))
Run the script

Note
Windows PowerShell includes a security setting called the execution policy that determines how scripts are run. By default, the execution policy is set to Restricted, which prevents any scripts
from running. To run the installation scripts for Microsoft Dynamics AX components, we recommend that you set the execution policy to RemoteSigned by using Set-ExecutionPolicy cmdlet.
This setting allows you to run scripts that youve written and scripts that have been signed by a trusted publisher.
1. On the server where you want to run the script, open the tools folder where the PowerShell scripts are installed.
2. If youre using Windows Server 2012 or a later operating system, use Windows Explorer to open the folder where the scripts are installed. Then click File > Open Windows PowerShell >
Open Windows PowerShell as administrator.
If youre using Windows Server 2008 R2 or an earlier operating system, start pw_wps as the administrator. Then, change the directory by using the following command: CD<Pathto
directory>.
3. Run the following command to verify and install prerequisites for the online store:
.\InstallPrereqs-SPFarm.ps1 oob-topology.xml oob-settings.xml
When the system finishes the operation, you can run the next script.
Generate-WSP.ps1
This script creates a SharePoint solution package (.WSP file) for your computing environment. The solution package includes properties such as connection strings, URLS, and ports from the
oob-topology.xml and oob-settings.xml files. The solution package also includes binaries and static web files that were deployed by Microsoft Dynamics AX Setup to the Retail Online Channel
directory.
Run Generate-WSP.ps1:
In the Windows PowerShell console, run the following command to generate the WSP file for the online store:
.\Generate-WSP.ps1 oob-topology.xml oob-settings.xml
Important
Due to a known issue, the following script can fail with a file access error. If the script fails, re-run it. It should finish successfully the second time.
When the system finishes the operation, you can execute the next script.
Deploy-FarmSolutions.ps1
This script performs the following actions on the server.
Deploys the new SharePoint solution package

Activates features
Runs post-deployment custom scripts (deploy mode)
If you re-run this script, the system performs the following actions before deploying the solution package or activating features. You can toggle options to preserve settings, as described earlier
in this document.
1. Deactivates features
2. Uninstalls solution packages
3. Runs post-deployment custom scripts (retract mode)
Run Deploy-FarmSolutions.ps1:
In the Windows PowerShell console, run the following command to deploy the solution to SharePoint.
.\Deploy-FarmSolutions.ps1 oob-topology.xml oob-settings.xml
When the system finishes the operation, you can verify the deployment.
Verify deployment
If all deployment scripts completed without errors, use this section to help verify the online store deployment. If the deployment scripts returned errors, see Troubleshoot installation issues for a
Retail online store.
Verify that the Connector Service is running: After a successful deployment, the Retail Publishing Connector Service 1 is running in SharePoint Central Administration. At this point, the service
displays an error No channel configuration could be found in the database, which means that the channel has not been configured in Microsoft Dynamics AX yet. For information about
configuring a channel, see the section titled Set up the online store in Microsoft Dynamics AX in the Online Store
Use the following procedure to verify that the Dynamics AX Publishing Connector service is running.
1. In SharePoint Central Administration under System Settings, click Manage services on server.
2. Verify that the Retail Publishing Connector Service 1 is running.
3. In SharePoint Central Administration, click Monitoring, and then click Check job status.
4. Verify that you see jobs listed for the C1 Application for Retail Store Front Internal and the Out of box Store front Public.
Verify that site collections exist and can be browsed: After a successful deployment, you can view the Retail online store web applications and site collections in SharePoint Central
Administration. If you specified different URLs for your web applications, you must adjust the URLS below accordingly.
Note
If you installed the Fabrikam starter store, change port values below from the 40,000 range to the 50,000 range. For example: The Contoso starter store product catalog site is
http://ServerName:40001/sites/RetailProductCatalog. The Fabrikam starter store product catalog site is http://ServerName:50001/sites/RetailProductCatalog.
1. In SharePoint Central Administration, click Application Management, and then click View all site collections.
2. On the C1 Application for Retail Store Front Internal web application, copy the http://ServerName:40001/sites/RetailProductCatalog URL and paste it into a browser. Verify that the
Welcome to your product catalog site displays.
3. In SharePoint Central Administration, click the Web application drop-down list and then click Change web application.
4. Click the Out of box Store front Public web application.
5. In the URL section, verify that you see the following URLs:
http://ServerName:40002/sites/RetailPublishingPortal
http://ServerName:40002
6. Copy and paste each URL into a browser. Verify that you see the Contoso electronic superstore site and the Contoso electronic superstore sign-in site. If the sign-in site displays a
certificate warning, click Continue to this web site. This warning appears if you used a self-signed certificate.
Verify that you can create and sign-in with a new forms-based user account: You should be able to register a new user account and logon from the public URL. By completing the sign-up
process you verify SQL Server connectivity, SSL port settings, and SSL certificate bindings.
1. Paste the public URL into a browser and press Enter. For example: http://ServerName:40002/sites/RetailPublishingPortal
2. Click Register a new account.
3. Enter an email address and a strong password in the required fields and then click Create account. Note that if you see more than one email and password field on the page, it means that
you executed the Deploy-FarmSolutions.ps1 script multiple times on this server. This is a known issue. To create the forms-based user account, you must enter the email address and strong
password in each field. Also note that you receive an error after you register the account because the online channel has not been configured in Microsoft Dynamics AX.
4. Browse the public portal site again (http:// ServerName:40002/sites/RetailPublishingPortal).
5. Click the Sign In link and enter the information for the account that you just created. The system logs you onto the Contoso electronics site as a registered user.
Verify that you can browse the public URL: If you registered a domain, you should be able to browse the web address for your site. For example, you should be able to browse
http://www.<your_domain>.com/sites/RetailPublishingPortal. If you have not yet registered the domain then you must create a hosts file entry and disable proxy settings in your browser (if
applicable) before you attempt to browse the web address.
Next steps for developers

Step
Detail
Review the quick guide for

customizing the online store.
See Quick Guide: How to customize a Microsoft Dynamics AX for Retail online store.
Set up the online channel
After you deploy the Microsoft Dynamics AX Retail online store, you must setup the online channel in Microsoft Dynamics AX. See the Online store setup
checklist. The checklist is available in the Microsoft Dynamics AX client: Retail > Setup > Online store setup checklist.
Note
If the online channel has already been set up in Microsoft Dynamics AX then you only need to publish the channel and publish a catalog. For information, see
Publish an online store in Set up an online store and Publish a catalog in Key tasks: Create retail product catalogs.
Customize and rebrand the

starter store
See the Extend section of the Online Store.
Deploy a second online store
Install multiple Microsoft Dynamics AX Retail online stores
Deploy to production
See Deploy your solution to a production environment in Quick Guide: How to customize a Microsoft Dynamics AX for Retail online store.
Uninstall an online store

The method that you use to uninstall an online store varies depending on the method you used to install the store.
Caution
Before you uninstall, we strongly recommend that you back up your SharePoint farm. If you don't follow the instructions completely, your content database may be corrupted.
Uninstall if you used Setup to install

If you installed an online store by using Setup, then you can either run Setup again to remove it, or use Control Panel > Add or Remove Programs.
Uninstall if you installed with Windows PowerShell

If you used settings and topology files to configure the online store, then Run the undeploy script from the Microsoft Dynamics Windows PowerShell prompt. The following example removes the
default instance deployed by Setup.
C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Online Channel\Tools\UnDeployRetailOnlineChannel.ps1 -TopologyXmlFilePath oob-topology-updated.xml -SettingsXmlFilePat
To remove a non-default instance, change the name of the xml file in the parameters to the appropriate file.
C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Online Channel\Tools\UnDeployRetailOnlineChannel.ps1
-TopologyXmlFilePath oob-topology-updatedFabrikam.xml
-Setting
Note
If you have multiple online channels, you must use run the script with the appropriate settings and topology file for each online channel.
Uninstall if you installed with Windows PowerShell, and no longer have the original settings and topologies file
Use the following procedure if you installed with a settings file, but no longer have the file.
1. In SharePoint Central Administration, under System Settings, click Manage Farm Features.
2. Clear Claims Provider, Logging Service, and Publishing Job. If these features are not present, skip this step.
Note
Site level features will be automatically uninstalled when we uninstall the parent solutions.
3. In Central Administration, under System Settings, click Manage Farm Solutions. For each of the following solutions, choose to retract immediately, and then click OK.
Publisher Job
StoreFront
Common Global Modules
Note
This package is shared across all instances of storefront.
Note
While you are completing these steps, an IIS reset will occur, and Central Administration might become unavailable. If so, wait and try again.
4. After all the solutions have been retracted, remove the solution for each entry.
a. In Central Administration, under Manage Web Applications, delete all of the Web Applications by clicking Delete, and then clicking Delete Web Application.
b. Click Yes when you are prompted to delete content databases and to delete IIS web sites. This step can take some time to complete.
See also
Online Store
Announcements: To see known issues and recent fixes, use Issue search in Microsoft Dynamics Lifecycle Services (LCS).
2014 Microsoft
Install multiple Microsoft Dynamics AX Retail online stores [AX

2012]
Updated: April 28, 2014
Applies To: Microsoft Dynamics AX 2012 R3
This topic describes how to create a second Microsoft Dynamics AX Retail online store. You deploy a second online store by using Windows PowerShell after you make
changes in the oob-settings.xml and oob-topology.xml files. The second online store shares some components with the first or primary online store. In the context of the
Microsoft Dynamics AX Retail online store, these shared components are combined into an entity called Common Global Modules.
Before you begin

You must complete the following tasks before you deploy a second Retail online store.
Task
Details
Install the primary online

store
A second online store shares global components with the primary online store. You must install a primary online store before you
install a second store. For more information, see Install a Microsoft Dynamics AX Retail online store (e-commerce).
Create a copy of the

primary online store XML
files
Locate the oob-settings.xml and oob-topology.xml files for the primary online store in the following folder:
Make a copy of these files so that you have a record of the settings used for the primary online store.
Install a second online store

You must install the second online store by using Windows PowerShell. And you must configure the following parameters in the oob-settings and oob-topology XML
files. Because you made a copy of the primary online store XML files, you can update parameters directly in the XML files in the C:\Program Files (x86)\Microsoft
Dynamics AX\60\Retail Online Channel\tools folder.
Oob-settings.xml
Specify unique values for the following parameters in the oob-settings.xml file.
SharepointPackageInstanceIdentifier
StoreFrontUrlPort_Public
StoreFrontUrlPort_SSL_Public
StoreFrontUrlPort_Internal
ProductCatalogUrlPort_Internal
DestinationId
ChannelOperatingUnitNumber
The following values must be identical for multiple online stores in a SharePoint web farm.
IdentityProviderDatabaseServerName
CustomClaimsProviderDatabaseServerName
The following values can be identical or different for multiple online stores in a SharePoint web farm.
ChannelDatabaseServerName
ChannelDatabaseServerNamedInstanceNam
Oob-topology.xml
Update the following parameters in the oob-topology.xml file.
1. Disable deployment for the CommonGlobalModules. These globally shared components were installed with the primary online store deployment. Set the
following parameters to false, as shown here:
<WSPPackage generate="false" deploy="false" retract="false"> <RootFolder>..\CommonGlobalModules</RootFolder>
2. Disable the custom claims provider feature. These globally shared components were installed and activated with the primary online store deployment. Set the
following parameter to false, as shown here:

<FeatureToActivate activate="false" name="SharePoint.Web.Storefront_CustomClaimsProviderSettingsFeature_[SharepointPackageInstanceIdentifier]"
urlXpath="Settings/SiteCollection[@id='RetailPublishingPortal']/Url" />
3. Disable the TrustedIdentityTokenProvider. You will reuse the identity providers that were installed with the primary online store deployment. Set the following
parameters to false, as shown here:
<TrustedIdentityTokenIssuer id="Facebook" install="false" deleteifexists="false">
5. Run the Windows PowerShell commands to install the second online store. For more information, see Install a Microsoft Dynamics AX Retail online store (ecommerce).
See also
Online Store
2014 Microsoft
Set up and configure a Microsoft Dynamics AX Retail online store

[AX 2012]
If you deployed the online store, you are ready to set up the online channel in Microsoft Dynamics AX. Setup procedures are listed in the Online Store under the heading
Setup and configure an online store. The topics in the roadmap supplement the online store setup checklist. The checklist is available in the Microsoft Dynamics AX client:
Retail > Setup > Online store setup checklist. Use the procedures listed in the documentation roadmap and the checklist to finish setting up and configuring the Retail
Online Store.
See also
Install a Microsoft Dynamics AX Retail online store (e-commerce)
2014 Microsoft
Configure clients computers to bulk edit attributes in Microsoft

Excel [AX 2012]
Updated: July 12, 2013
Microsoft Dynamics AX users can bulk edit product attributes for a retail catalog by using Microsoft Excel. The bulk-edit process uses a macro created specifically for
Microsoft Dynamics AX. By default, macros are disabled in Excel. This topic describes how to enable signed macros in Excel and how to verify that Microsoft is a trusted
macro publisher. After you perform the steps in this topic, Microsoft Dynamics AX users can perform a bulk edit, as described in Bulk edit product attributes by using Excel.
Important
You must perform the following procedures on each computer that will bulk edit attributes.
Enable signed macros in Excel

A signed macro includes a digital signature that identifies the creator and verifies the safety of the macro. Microsoft Dynamics AX 2012 R2 includes a macro signed by
Microsoft for bulk editing catalog attributes. You must enable signed macros in Excel before Microsoft Dynamics AX users can use the macro. Configuring macros with
the following procedure has the following effect:
Macros are disabled, but security alerts appear if there are macros present. However, if the macro is digitally signed by a trusted publisher, the macro runs if you have
trusted the publisher. If you have not trusted the publisher, you are notified to enable the signed macro and trust the publisher.
1. On the client computer that will be used to bulk edit attributes, open Excel.
2. Click File, and then click Options.
3. In the Excel Options form, click Trust Center, and then click the Trust Center Settings button.
4. In the Trust Center form, click Macro Settings.
5. Click Disable all macros except digitally signed macros, and then click OK.
Verify that Microsoft is listed as a trusted publisher

If Microsoft is listed a trusted publisher in Excel, Microsoft Dynamics AX users can use the bulk edit macro without being prompted to enable the macro.
1. On the client computer that will be used to bulk edit attributes, open Excel.
2. Click File, and then click Options.
3. In the Excel Options form, click Trust Center, and then click the Trust Center Settings button.
4. In the Trust Center form, click Trusted Publishers. Verify that Microsoft Corporation and Microsoft Code Signing PCA are listed in the form. There could be
several Microsoft certificates listed on the form. Verify that at least one Microsoft certificate has not expired. If a valid certificate exists, click OK. Microsoft
Dynamics AX users on the local computer can now use the bulk edit macro in Excel. If no Microsoft certificate is listed, import a valid excel-cert.cer certificate into
the local computer certificate store.
5. From the Windows desktop, click Start and then click Run.
6. Type MMC and press Enter.
7. Click Certificates and then click the Add button (>).
8. Click Computer account and then click Local computer.
9. In MMC, expand Certificates and right-click Trusted Publishers.
10. Click All Tasks and then click Import.
11. Use the Certificate Import wizard to import a valid excel-cert.cer file and then click OK.
12. Accept the default values.
13. In the Excel Trust Center form, click Trusted Publishers. Verify that Microsoft Corporation and Microsoft Code Signing PCA are listed in the form. There could be
several Microsoft certificates listed on the form. Verify that at least one Microsoft certificate has not expired. If a valid certificate exists, click OK.
See also
Online Store
Getting started with customizing the Retail online sample store [AX
2012]
Retail in Microsoft Dynamics AX 2012 R3 includes starter stores that you can customize: the Contoso store that sells electronics and the Fabrikam store that sells clothing.
These stores are built on the Microsoft SharePoint Server 2013 cross-site publishing platform. Source code and sample customizations for the starter stores are included
in the Retail SDK.
Before you begin working with the Retail online sample stores, you should understand the technologies that support the online stores.
To understand the capabilities in Microsoft SharePoint Server 2013, see Build sites for SharePoint 2013.
In AX 2012, you set up Retail catalogs as part of configuring an online store. For more information, see Set up an online store and Configure online store products
in Microsoft Dynamics AX.
For a step-by-step guide to creating an online shopping site by using SharePoint, see How to set up a product-centric website in SharePoint Server 2013.
The following articles can help you to understand the capabilities and design of the Retail online sample stores.
System architecture for the Retail online store

Retail online store publishing architecture
The following table lists some of the common tasks in customizing a starter store.
How do I
Topics
Understand the lifecycle of a Retail online store
Online Store
View the functionality and appearance of the online sample stores on a demonstration virtual machine
Microsoft Dynamics AX 2012 Solution Demos*
Learn how the Retail online sample stores authenticate users and administrators, and learn how to add
a logon provider such as Facebook
Create customizations of the components of the Retail online sample stores
Components of the Retail online sample store
Extend customer data in the online store
Walkthrough: Adding a table for customer preferences to the

AX 2012 database
Walkthrough: Extending the CRT to add customer preference
data for Retail clients
Walkthrough: Extending retail data distribution infrastructure
for customer preferences
Walkthrough: Adding customer preferences to the Retail
online sample store
Customize the appearance and behavior of the user interface for the Retail online sample store
Debug customizations in the Retail online sample stores
Debug code in a Retail online sample store
Deploy customizations to a test environment
Quick Guide: How to customize a Microsoft Dynamics AX for

Retail online store
Use tools to help you configure publishing jobs, update the channel against which the online store
operates, and clean up your SharePoint site.
Microsoft Dynamics AX for Retail online channel tools
Note
*To access this site, you must be enrolled in a service plan.
Understanding the functionality of Retail online sample stores

Before you begin to plan and design your customizations, consider the current functionality of the starter stores.
The Retail online sample stores extend the product catalogs and business data managed in Microsoft Dynamics AX 2012 to online shoppers. All the code for the Retail
online samples store is available for you to customize in the Retail SDK. The code supports sales transactions, manages authentication for new and returning customers,
and manages data by using the Commerce Runtime (CRT).
Data flow in Retail online sample stores

Data in the Retail online sample stores is stored in the AX 2012 database and two SharePoint site collections. Product catalog data includes all data about product
items: for example, color, size, and description. Other data displayed on the store pages includes information about customer accounts, transactions, and store
locations. These two types of data, product catalog data and publishing portal data, are stored in two site collections that are located in separate web applications.
For more information about these site collections that includes how security is implemented, see the Site collections section in the article Architecture of the Microsoft
Dynamics AX Retail online store.
Customizing product catalog data

You control the products that appear in your online store by configuring catalogs and data distribution parameters in Microsoft Dynamics AX 2012 when you
configure the online channel. For more information, see Configure online store products in Microsoft Dynamics AX.
The Retail online sample stores display products by using sample data in AX 2012. Several display templates are provided when you install the sample stores. You can
find them in the folder that is available when you map a network drive. The path to the folder resembles the following:
Z:\_catalogs\masterpage\Display Templates\Content Web Parts
To customize the appearance of products in the sample stores, you can:
Use standard SharePoint Content Search Web Parts to display the products. To view the web parts for the Retail online sample stores, open the SharePoint
Central Administration page and then click the Site Settings button and then click Web parts under Web Designer Galleries. For example, the Product Gallery
page uses the Product Gallery web part. For more information, see Content Search Web Part in SharePoint 2013.
Modify the sample display templates that are provided by changing code in the HTML files on the mapped drive. Each HTML file has a corresponding .js file
that SharePoint updates automatically after any changes that you make. For more information about mapping a network drive, see Map a network drive to the
SharePoint 2013 files for online stores.
Customize the CSWPs in the sample stores. For more information, see Edit existing Web Parts in SharePoint 2013.
Managing data in the store pages

The data distribution infrastructure manages data transfer from AX 2012 to the channel database. For example, data such as customer name and address are
displayed in the Contoso online sample store. For more information, see Configure and schedule retail data distribution.
CRT services support the transfer of data in the channel database to the online store. For more information, see Services Overview for Commerce Runtime.
The Retail online sample stores use a model-view-controller pattern to present data on store pages. Data from the CRT services is mapped to the object model and
then to the view model in code that supports the store pages. For an example that sets up this mapping for a new data element, see Walkthrough: Adding customer
preferences to the Retail online sample store.
Customizing the appearance of store pages

You can customize the appearance of store pages in two ways. You can:
Customize the pages that are available on the mapped network drive. For more information, see Map a network drive to the SharePoint 2013 files for online
stores and Customize the appearance and behavior of site pages.
Customize the pages in the source code provided in the Retail SDK in the Online Channel\Storefront folder. Open the Storefront.sln solution to view the code.
After you rebuild the solution, you can deploy your changes to create your customized site.
For more information about each component and the data elements that are included in the Retail online sample stores, see Components of the Retail online sample
store.
See also
Retail SDK
2014 Microsoft
Architecture of the Microsoft Dynamics AX Retail online store [AX

2012]
The Microsoft Dynamics AX Retail online store enables you to deploy, manage, and customize an online sales channel that is fully integrated with Microsoft Dynamics AX.
The online store is built on the Microsoft SharePoint Server 2013 cross-site publishing platform. Cross-site publishing uses one or more authoring site collections to author
and store content, and one or more publishing site collections to control the design of the site and to show content. The authoring site collection can contain catalogs such
as Pages libraries, and lists of items that are tagged with metadata. These catalogs are indexed by the search system and made available to the Publishing Portal. The
Publishing Portal displays previously indexed data on web pages by using search-driven Web Parts.
This topic describes the architecture, features, and components of the Retail online store. Before you continue, we suggest that you learn about the features and
architecture of SharePoint cross-site publishing. For more information, see Plan for cross-site publishing in SharePoint Server 2013 and Plan the logical architecture for
cross-site publishing in SharePoint Server 2013.
Features and components of the Retail online store

This section describes the features and components of the Retail online store. Figure 1 shows the logical architecture and the flow of information between some of the
features and components discussed in this section.
Figure 1 High-level architecture of the Retail online store
Real-time Service
The Commerce Data Exchange: Real-time Service is a Windows Communication Foundation (WCF) service that uses .NET Business Connector to facilitate
communication between Microsoft Dynamics AX Retail headquarters and the Microsoft Dynamics AX commerce runtime (CRT). In previous releases, this service was
called the Retail Transaction Service. This service is installed by using Microsoft Dynamics AX Setup. For more information about this service, see Install Commerce
Data Exchange: Real-time Service (Retail Transaction Service).
Commerce Data Exchange: Async Server

Commerce Data Exchange: Async Server is part of the system for asynchronous data exchange between Microsoft Dynamics AX and retail channels such as the Retail
online store. Async Server is installed at headquarters and communicates with Microsoft Dynamics AX. For more information, see Commerce Data Exchange: Async
Server.
Commerce Data Exchange: Async Client

Commerce Data Exchange: Async Client is part of the system for asynchronous data exchange between Microsoft Dynamics AX and retail channels such as the Retail
online store. Async Client is installed at the channel, and communicates with the channel database. Typically, you will install one instance of Async Client for each
channel. For more information, see Commerce Data Exchange: Async Client.
Commerce runtime
The Microsoft Dynamics AX commerce runtime is a set of .dlls that perform business logic and data processing for an online store. The CRT has four layers (data
access, services, workflow, API) and a database. For more information about the CRT, see Commerce Runtime.
Search
The Microsoft SharePoint Server 2013 cross-site publishing platform uses Microsoft FAST Search and search-driven pages to dynamically display content for
customers. For more information about FAST Search in cross-site publishing, see Plan search for cross-site publishing sites in SharePoint Server 2013
Term sets
You use term sets to tag catalog content such as pages or list items on the authoring site. By doing this, terms help categorize the content into a hierarchy. These
same terms are later used on the publishing site to issue queries, show information about category and catalog item pages, create friendly URLs, and for managed
navigation. For more information, see Plan terms and term sets in SharePoint Server 2013.
Retail online store databases

When you deploy the online store, the system creates the following databases in Microsoft SQL Server.
Channel database(s): The online store uses this database as a data store before pushing data into SharePoint. By default, the database is named AxRetailSP.
Settings for this database are stored in the oob-topology.xml file under Settings/Channel.
Identity Provider database: This database stores user credentials for forms-based authentication. By default, the database is named SPFBA. Settings for this
database are stored in the oob-topology.xml file under Settings/IdentityProvider.
Custom Claims Provider database: This database stores the mapping between a users identify and their Microsoft Dynamics AX customer number when the
user has created an account. By default, the database is named SPAuthZ. Settings for this database are stored in the oob-topology.xml file under
Settings/CustomClaimsProvider.
Figure 2 provides a detailed view of the Microsoft Dynamics AX Retail online store and SharePoint features and components.
Figure 2 Detailed view of the Retail online store architecture
The starter stores

Microsoft Dynamics AX 2012 for Retail includes two Retail online starter stores. The Contoso store is modeled after a fictitious online electronics retailer. The Fabrikam
store is modeled after a fictitious online clothing store. When you install the Retail online store by using Setup.exe or PowerShell, you specify which starter store to
deploy in your environment. You can then customize and rebrand the starter store to meet your needs. The starter stores consist of the following site collections and
controls.
Site collections
The product catalog and publishing portal site collections are located in separate web applications. The product catalog content web application uses AD DS to
authenticate content authors. The publishing portal web application uses AD DS authentication for designers and forms-based authentication for web users. This web
application is configured to allow anonymous access for web users. The product catalog site collection contains a list of product data, including the Microsoft
Dynamics AX navigational hierarchy which is stored in the SharePoint Term Store. Those lists created by the online store publishing process are shared.
Internal users such as designers and other content authors have Contribute permission level to add, update, and delete items in the asset library. The asset library is
added to the Suggested Content Browser Locations list for the authoring and product catalog site collections so that content authors can use those assets in their
content.The search system indexes content from the authoring site and the product catalog site collection. When a user views a page on one of the publishing sites,
queries from Search Web Parts on that page are sent to the search index. Results are returned from the search index, and shown in the Search Web Parts on the
page.
Figure 3 provides a detailed view of the web applications and site collections that are created on the SharePoint server when you deploy the Retail online store. Figure
3 also lists the associated classes for the applications and site collections.
Figure 3 Detailed view of the Retail online store web applications and site collections
The Microsoft Dynamics AX Connector (also named the Channel Connector) is a SharePoint service publishing job that runs in the context of the OWSTimer.exe
service, which is standard SharePoint Timer Windows service. The publishing job retrieves updated product, product schema, category hierarchy information from the
channel database and pushes it into the product catalog database. The information is then crawled by Search.
The Secure Token Service is a SharePoint service that is used for validating forms-based authentication users.
Controls
The starter online store includes the following customizable controls.
Control type
Available in starter store
Page layouts
Address edit
Associate customer
Change password
Checkout confirm
Facebook logon
Issue gift card
Logon
Loyalty
My account
Order review
Order confirm
Order history
Product details
Product gallery
Product quick view
Display templates
Contoso_Default_Item_ProductDetails
Contoso_Default_Item_ProductGallery
Contoso_Default_Item_ProductQuickView
Control_KitRetailListWithPaging
Control_ProductVariants
Control_RetailListWithCarouselPaging
Control_RetailListWithPaging
Control_RetailListWithPagingNoCrt
Fabrikam_Default_Item_ProductDetails
Fabrikam_Default_Item_ProductGallery
Fabrikam_Default_Item_ProductQuickView
Filter_RetailMultiValue
Filter_RetailMultiValue_Body
GiftCard_Item_ProductDetails
GiftCard_ProductVariants
Item_KitComponentDetails_Contoso_Default
Item_Recommended
Item_SelectComponentSubstitutesQuickView_Contoso_Default
Controls/Web parts
Shopping Cart
Mini shopping cart
Order history
Address display, edit
Customer display, edit
Wish List
Category landing
Welcome bar
Store product availability
See also
Online Store
2014 Microsoft
Retail online store publishing architecture [AX 2012]

This topic contains conceptual information to help developers and system administrators understand how channels and catalogs are published from the Microsoft
Dynamics AX Retail module to an online store in Microsoft SharePoint 2013 Products. Understanding the publishing process can help you develop, manage, and
troubleshoot your Retail online store. Before you read this topic, we recommend that you read about SharePoint cross-site publishing concepts. For more information, see
Plan for cross-site publishing in SharePoint Server 2013 and Plan terms and term sets in SharePoint Server 2013
Figure 1 shows the architecture and flow of the publishing processes. These processes are described in more detail in this topic.
Figure 1 High-level architecture of Retail online store publishing processes
Publish a Retail online store channel

To publish the Retail online store channel means to replicate the basic structure of your online store between Microsoft Dynamics AX and SharePoint. You create the
basic structure of your online store channel in the Microsoft Dynamics AX Retail module. The following set up tasks must be completed before you can publish the
channel:
1. Add the online store to the organization hierarchy. For more information, see Create or modify an organization hierarchy.
2. Create the online store and configure properties in Microsoft Dynamics AX. For more information, see Set up an online store.
3. Configure category hierarchy of you site. For more information, see Set up a retail hierarchy
4. Create the online store in SharePoint. Install a Microsoft Dynamics AX Retail online store (e-commerce).
After you completed these steps, you are ready to publish the product schema to SharePoint. Figure 2 shows the publishing process for a Retail online store channel.
Figure 2 Process flow for publishing a Retail online store channel
1. You create the online store in Microsoft Dynamics AX and publish it from the Online stores form. The publish status changes from Draft to In progress.
2. Microsoft Dynamics AX takes a snapshot of the category hierarchies (called the Retail hierarchy) and properties.
3. The Commerce Data Exchange: Async server reads information about the online store, hierarchies, and properties in the Retail store database and sends it to the
Commerce runtime (CRT).
4. The Async server synchronizes the tables in the channel database.
5. The Retail publishing job, which runs as a SharePoint timer job, receives information about synchronized tables from the CRT API and creates hierarchies for the
site that you created in SharePoint.
6. The Retail publishing job creates term sets in SharePoint.
7. The Commerce Data Exchange: Real Time Service receives the status of the Retail publishing job actions from the CRT API and publishes that status in Microsoft
Dynamics AX. The status shows either Published or Error.
For the specific procedures to publish a channel, see Set up an online store. After you published the channel, you can publish a catalog.
Publish a Retail online store catalog

A Retail product catalog lets you identify the products that you want to offer in your online stores. When you create a catalog, you identify the online stores where the
products will be offered, add products, and enhance the product offerings by adding merchandising details. After the catalog is approved, you publish it to make
products available in the online store. The following set up tasks must be completed before you can publish a catalog:
1. Set up retail products and configure hierarchies, assortments, and variants. For more information, see Setting up retail products
2. Set up retail product catalogs and configure attribute groups and workflow. For more information, see Setting up retail product catalogs.
Figure 3 shows the publishing process for a Retail online store catalog.
Figure 3 Process flow for publishing a Retail online store catalog
1. Microsoft Dynamics AX reads the product tables in the Retail database.

2. The Commerce Data Exchange: Async Server synchronizes all products in the channel database.
3. The CRT/Publishing Connector creates a listing. A listing is an instance of a product for a channel at a given point in time. For example, a product might be jeans
and the variant might be red. The system creates a listing for red jeans.
4. The system determines whether any new attributes were added for the listing. If a new attribute exists, for example if the listing red jeans includes a new
attribute called texture, and this attribute is marked as Included at the channel level, then the system creates a custom site column for that attribute. The
system creates a new rule for this list item and finishes the process in SharePoint by creating a new row for the red jeans listing.
5. The CRT records the publishing status for the listing.
6. The Commerce Data Exchange: Async Server synchronizes the publishing status of the red jeans listing with all other publishing statuses.
7. The status shows either Published or Error.
Note
To learn more about custom site columns and list items, see Introduction to Columns and the section titled "Share a library or list as a catalog" in Configure cross-site
publishing in SharePoint Server 2013.
Figure 4 shows the various features of an Microsoft Dynamics AX Retail catalog. When these features are published, they are mapped to the SharePoint cross-site
publishing platform.
Figure 4 Mapping of Microsoft Dynamics AX catalog features after they are published to SharePoint
See also
Update the Publishing Job Configuration
Microsoft Dynamics AX for Retail online channel tools
2014 Microsoft
Plan for a Microsoft Dynamics AX Retail online store [AX 2012]

Updated: August 26, 2013
The Microsoft Dynamics AX Retail online store is built on the cross-site publishing features of Microsoft SharePoint Server 2013. For information about how to plan a Retail
online store, see Plan for cross-site publishing in SharePoint Server 2013. As you read these planning materials, know that you do not have to create applications or sites
from scratch as discussed in the Microsoft SharePoint Server 2013 planning document. When you deploy the Microsoft Dynamics AX Retail online store, you deploy a
starter store that includes pre-constructed web applications, sites, and services. You can then configure, customize, and rebrand the starter online store to meet your
needs.
See also
Online Store
Architecture of the Microsoft Dynamics AX Retail online store
Install a Microsoft Dynamics AX Retail online store (e-commerce)
2014 Microsoft
Quick Guide: How to customize a Microsoft Dynamics AX for Retail

online store [AX 2012]
This topic describes how to customize the online store by using SharePoint features and the Visual Studio source-code projects that are included in the Retail SDK. This
topic also describes how to deploy customizations in development, test, and production environments. For information about developer prerequisites, including Microsoft
Visual Studio, see Set up the development environment for SharePoint 2013.
Before you begin

Use SharePoint features to change the look and feel of the application
SharePoint enables you to customize the user interface of the application. Developers and administrators can edit master pages, change styles, add new pages, and
change web part properties, to name a few options. You can perform these tasks in SharePoint or with 3rd party development tools that access SharePoint. It is
recommended to use these tools for the initial customization process. For information about modifying web parts, including the Content Search Web Parts that display
products in the store, see Edit existing Web Parts in SharePoint 2013.
Use the SDK to change the behavior, look, and feel of the application
The Retail SDK includes the source code of many retail online store features. By examining the source code, you can understand the application and adapt it to meet
your needs. For example, you can implement shipping-provider calculations in the Commerce Runtime, add support for a new identity provider, or add more businessrelated logging to understand what online users are doing at certain stages of the checkout process. All of these changes require you to change source code. The
following information describes how to customize the Retail online store by using the Retail SDK and then deploy those changes in different environments.
Install developer tools and features

You must install the Retail SDK, the Retail Online Channel, and the latest Microsoft Dynamics AX 2012 R2 cumulative updates on the SharePoint server before you can
customize the Retail online store. If you deployed the Retail online store as described in Install a Microsoft Dynamics AX Retail online store (e-commerce), then you
have already installed the Retail Online Channel and the latest cumulative update. Use the following procedure to verify that the server has the required tools, features,
and updates for customizing the Retail online store.
1. On the SharePoint server locate the following directories:

C:\My Documents\Retail SDK
-andC:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Online Channel
2. If you do not see these folders, then you must install the Retail SDK and the Retail Online Channel by using Microsoft Dynamics AX Setup.exe. For more
information, see Install retail components.
3. If you have not done so, download and install the latest cumulative update for Microsoft Dynamics AX 2012 R2.
Prepare your developer environment for signing updated source code

The process of customizing the Retail online store requires that you recompile the source code in the Visual Studio projects. After you recompile, the fully-qualified
name of the rebuilt assemblies will be different than the assemblies originally provide by Microsoft. Before you can recompile the assemblies, you must provide a
code signing key file (also called a strong name key file) to sign the customized code. If your business has a code signing key file (.snk file), you can reuse this file. If
you do not have a code signing key file, Visual Studio can create one for you. You must create a new project and enable code signing. Then, create a second project
that references the .dll of the output of the first project. You can locate the thumbprint in the assembly reference of the .csproj file in the second project. Once you
have the .snk file, you must do the following:
1. Save the file in the Retail SDK folder and give it a name Name.snk.
2. Edit the UpdateAssemblyIdentities.ps1 file in the Retail SDK folder. You must update the version number and the thumbprint of the key file (lines 97, 98).
3. Update the source code to use the strong name certificate by executing the UpdateAssemblyIdentities.ps1 script. This script can take several minutes to
complete.
Use Visual Studio 2012 to customize the Retail Online Store source code projects
Customization of the Retail online sample stores requires Microsoft Office Developer Tools for Visual Studio. Use the following steps to install the tools.
To download the Microsoft Web Platform Installer, see Microsoft Web Platform Installer.
To install Microsoft Office Developer Tools for Visual Studio

1. Open the Web Platform Installer, type SharePoint in the search box, and then press Enter.
2. Select Microsoft Office Developer Tools for Visual Studio 2012.

3. Click Add and then click Install.
The Retail SDK includes the following Visual Studio solution files:
Services.sln: Use this file to customize source code for the Commerce Run-time. The file is located in the Retail SDK\Commerce Run-Time\Services directory.
StoreFront.sln: Use this file to customize source code for the Retail online store. The file is located in the Retail SDK\Online Channel\StoreFront directory.
A typical development scenario might proceed as follows:
1. The developer opens the Services.sln project in Visual Studio, clicks Clean All, customizes the solution, and then clicks Build All.
Visual Studio creates the output assembly files in the Retail SDK\Commerce Run-time\References directory.
2. The developer opens StoreFront.sln, project in Visual Studio, clicks Clean All, customizes the solution, and then clicks Build All.
Visual Studio creates the output assembly files in the Retail SDK\Online Channel\References directory.
3. In Visual Studio, the developer right-clicks the StoreFront project node in the StoreFront solution, and then clicks Publish. By default, Visual Studio publishes
the updated solution to the C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Online Channel\StoreFront\ORIGINAL_WSP directory. If this directory does
not exist in your development environment, then you must create it.
The publish process creates a new deployment package which you can deploy in a test environment to verify your changes.
Deploy customizations in a test environment and verify your changes

Use the following procedure to deploy the Retail online store .wsp package you just created in a test environment to verify your customizations.
1. Open the C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Online Channel\tools\oob-topology.xml file in Microsoft Visual Studio or a text editor, such
as Notepad.
2. Search in the oob-topology.xml file for the parameters listed in the following table. Enter the specified value for each parameter.
Search for
Verify or change with
<WSPPackage generate="true" deploy="true"

retract="true"> <InputFolder>..\ RetailJobs \SP</InputFolder>
Verify that <WSPPackage generate="true"

retract="true"> <InputFolder>..\Contoso DemoData \SP</InputFolder>
Verify that <WSPPackage generate="true"

retract="true"> <InputFolder>..\ StoreFront \SP</InputFolder>
Change <WSPPackage generate="true" to

false
3. From a command prompt, open the directory where the oob-topology file is stored. By default, it is stored here:
4. Execute the following command:
powershell .\Generate-WSP.ps1 oob-topology.xml oob-settings.xml
5. After the PowerShell command is finished, update the oob-topology.xml file so that the RetailJobs and DemoData XML nodes specify generate=false and the
StoreFront XML node specifies generate=true.
6. Execute the following command:
powershell .\Prepare-FromWSP.ps1 oob-topology.xml oob-settings.xml
7. After the PowerShell command is finished, execute the following command:
powershell .\InstallPrereqs-SPFarm.ps1 oob-topology.xml oob-settings.xml
8. After the PowerShell command is finished, execute the following command:
powershell .\Deploy-FarmSolutions.ps1 oob-topology.xml oob-settings.xml
9. Save your changes in the oob-topology.xml file.
10. Verify all of your changes. For more information, see Verify deployment in Install a Microsoft Dynamics AX Retail online store (e-commerce).
Deploy your solution to a production environment

To deploy a customized Retail online store into a production environment, you must complete the processes described in the following table.
Process
Details
Verify that the Retail

online channel has been
installed and configured
in Microsoft Dynamics
AX
Setup procedures are listed in the Online Store under the heading Setup and configure an online store. The topics in the roadmap
supplement the online store setup checklist. The checklist is available in the Microsoft Dynamics AX client: Retail > Setup > Online
store setup checklist. Use the procedures listed in the documentation roadmap and the checklist to finish setting up and configuring
the Retail online channel.
Copy the deployment

packages and all
associated files to the
Web server farm
After you have verified your customized Retail online store, you can copy the C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail
Online Channel directory to the Web server farm.
Update the oobtopology.xml file for the

production environment
Open the oob-topology.xml file in the production environment. Verify that all WSPPackage XML nodes are configured with
generate=true. If any node is configure with generate=false, then you must change the value to generate=true.
Verify identity settings in

SharePoint configuration
files.
Caution
You must review and configure cookie behavior in SharePoint configuration files. If you do not configure these settings, your Retail
online store might display sensitive user information to different users. For example, the default behavior for SharePoint is to use
persistent session cookies. This enables a user to close the browser, re-open the browser, and re-visit a SharePoint web application
without signing in again. For more information, see Federated Identity for SharePoint Applications.
2014 Microsoft
Set up and configure refiners for a Retail online store [AX 2012]
This topic describes how to set up and configure refiners for a Microsoft Dynamics AX Retail online store. Refiners are a component of search-driven navigation on a web
page.
You can add refiners to a page to help users quickly browse to specific content. Refiners are based on managed properties from the search index. For example, in a Retail
online store, a refiner could be a color, a brand, or a material for a product in your catalog. If you specify a color refiner, The Refinement Panel Web Part will show the
available colors for a product. When users click a specific color, only the selected colors are listed.
Refiners are used with terms in a term set in SharePoint Server 2013 faceted navigation. Faceted navigation helps users browse for content more easily by filtering on
refiners that are tied to terms in a term set. By using faceted navigation, you can configure different refiners for different terms in a term set without having to create
additional pages. For example, in an Internet business scenario in which a catalog of electronic products is shown, a term set might be used to categorize different
products, such as computers or cameras. The same category page is used for both terms. After you enable the managed properties Screen size and Megapixels as
refiners, you can configure faceted navigation so that Screen size is shown as a refiner for computers, and Megapixels is shown as a refiner for cameras. This means that
you do not have to create additional pages to guide users to content that is relevant for a specific category. For more information, see "Plan refiners and faceted
navigation" in Plan search for cross-site publishing sites in SharePoint Server 2013.
This topic includes the following sections.
Map a network drive

Configure refiners
Configure refiner labels
Map a network drive

The procedures in this topic require that you map a WebDAV network drive for the Retail online store publishing portal and the product catalog. By default the URLs for
the Contoso publishing portal and catalog are as follows:
http://ServerName:40003/sites/RetailPublishingPortal
http://ServerName:40001/sites/RetailProductCatalog
For the Fabrikam publishing portal and catalog, substitute 40003 and 40001 with 50003 and 50001. Use the procedure in the following topic to map a WebDAV network
drive for each of these URLS: Map a network drive to the SharePoint 2013 files for online stores
Configure refiners
Use the following procedure to set up and configure refiners for a Retail online store. This procedure describes, as an example, how to configure a Retail price refiner.
Note
The following procedure requires that you select a display template. You can select one of the default SharePoint templates or you can copy an existing template and
customize it. For more information, about default display templates, see the SharePoint Server 2013 Display template reference.
1. Use Windows Explorer to open the following folder on the RetailPublishingPortal network drive:
%Portal_Drive%:\_catalogs\masterpage\Display Templates\Filters
2. Copy the following files:
Filter_MultiValue_Body.html
Filter_RetailMultiValue.html
3. Paste the files into the following folder on the RetailProductCatalog network drive:
%Catalog_Drive%:\_catalogs\masterpage\Display Templates\Filters
4. Press F5 on the keyboard to refresh the folder view on the RetailProductCatalog network drive. Verify that you see the following four (4) new files in the folder:
Filter_MultiValue_Body.html
Filter_MultiValue_Body.js
Filter_RetailMultiValue.html
Filter_RetailMultiValue.js
5. In a web browser, open the product catalog site. By default, the URL is http://ServerName:40001/sites/RetailProductCatalog
6. Click Manage item hierarchy in Term Store.
7. On the Site Settings Term Store Management Tool page, in the left pane, expand the Site Collection ServerName SitesRetailProductCatalog node.
8. Expand Product Hierarchy and then click a category.

9. In the right pane, click the Faceted Navigation tab and then click Customize Refiners.
10. Locate RetPrice in the list of available refiners. Click Add.
11. Select an option from the Display template list. For example, select Retail Multi-value Refinement Item.
12. Click Custom and specify price ranges. For example: 5;10;50;100;500
13. Click OK and then click Save.
14. Repeat steps 8-12 as needed to create more refiners for the same or for different categories.
Important
By default, child categories recursively inherit all refiners specified on a parent category. If you want to specify a different set of refiners for a child category (a
common scenario) then you must break inheritance and add specific refiners, as needed. To break inheritance, select a child category and then click Stop
inheriting. The Customize refiners button is now active. Click this button to set up additional refiners on the child category.
15. Validate you changes in the publishing portal. Open the portal in a Web browser. By default, the URL is http://ServerName:40003/sites/RetailPublishingPortal. Click
a category and verify that you see the refiners you created.
Configure refiner labels

By default, refiner labels display the name of their corresponding managed property. For example, a managed property named RetColor displays a refiner label of
RetColor. If you want a refiner label to display something other than the name of the managed property, for example Color, and then you must configure labels as
described in the following procedure.
1. Create a list of each managed property that you want to configure to display a different refiner label. You can create this list in a simple text editor like Notepad.
2. Add the following prefix string to each managed property in the text editor: rf_RefinementTitle_
3. For each property, add a colon (:) followed by the new refiner label in parentheses. For example:
"rf_RefinementTitle_RetColor": "Color"
4. In Windows Explorer, open the following folder in the RetailPublishingPortal network drive that you mapped earlier in this topic:
%Portal_Drive%:\_catalogs\masterpage\Display Templates\Language Files\en-us\
Note
This procedure updates a file in the en-us folder, which means this procedure configures English language labels. To configure refiner labels in a different
language, modify the following file in a different language folder.
5. Edit the CustomStrings.js file.

6. Copy and paste the list of managed properties you created in the text editor into the CustomStrings.js file.
7. Save your changes in the file and then browse the publishing portal. By default, the URL is http://ServerName:40003/sites/RetailPublishingPortal.
See also
Quick Guide: How to customize a Microsoft Dynamics AX for Retail online store
Online Store
2014 Microsoft
Customize master pages [AX 2012]

The Microsoft Dynamics AX 2012 R2 Retail starter store is a site built by using the commerce runtime (CRT) and the new site authoring and publishing model in Microsoft
SharePoint Server 2013. For more information, see Overview of the SharePoint 2013 page model. You can use the Retail starter store as a basis for developing your own
online store. To customize the shared framing elements such as the header and footer for all the pages in your site, you can modify the sites master pages.
This topic shows you how to customize a master page by updating the Welcome page of the starter store.
To update a master page

1. Open a web browser and navigate to the Welcome page for the starter store. Typically, the URL for the Welcome page resembles the following:
http://<your-server-name>:40002/sites/RetailPublishingPortal
Note
Observe the behavior of the page. A slide show cycles through three pictures representing product categories. At the top left-hand side of the page, you can see
the Contoso logo.
2. Open a web browser on a computer where you are logged in using the administrative account for SharePoint.
3. Navigate to the Site Settings page of the store. Use port 40003 and sign in with administrative credentials. The link to the Site Settings page is typically found at a
URL that resembles the following:
http://<computer-name>:40003/sites/RetailPublishingPortal/_layouts/15/settings.aspx
Tip
Add this page to your Favorites to make it easy to return to it in the future.
4. Click Master pages and page layouts in Web Designer Galleries to view a list of files in the Master Page Gallery page.
5. Right-click a file that you want to edit, such as Storefront.master, and then click Check Out.
6. Right-click the file and then click Download a Copy.
7. Edit the file by using Visual Studio or another editor. For example, in the following code from Storefront.master, you can change the logo file that is displayed on
each page. The file is named logo_Contoso_main.png. You can edit that file or replace the file name with the name of a file that contains a graphic of similar size to
display your company logo. The following code shows the path and file name of the logo in the Storefront.master file:
<div class="msax-Main">
<div class="s4-notdlg msax-LogoBar">
<div class="msax-Logo">
<a id="A1" href="<% $SPUrl:~sitecollection/ %>" runat="server">
<img src="/_layouts/15/Images/Storefront/logo_Contoso_main.png" />
</a>
</div>
8. To upload the file and add your changes to the site, click Upload Document on the Files ribbon.
Tip
This procedure illustrates one way of changing master pages and page layouts for the online starter store. For more information about how to use Microsoft
SharePoint Server 2013 to modify the visual site design, see Develop the site design in SharePoint 2013.
9. Refresh the Welcome page in your initial browser session to see your changes.
Note
You can edit the master page files directly by mapping a network drive. For more information, see Map a network drive to the SharePoint 2013 files for online stores.
See also
How to: Apply a master page to a site in SharePoint Server 2013
2014 Microsoft
Customize page layouts [AX 2012]

The Microsoft Dynamics AX 2012 R2 Retail starter store is a site built by using the new site authoring and publishing model in Microsoft SharePoint Server 2013. You can
use the Retail starter store as a basis for developing your own online store. You can customize individual site pages by modifying the page layout files.
Each page layout uses a specific master page, and each page has a corresponding page layout. For example, the welcome page for the site, Welcome.aspx, has a
corresponding page layout file called WelcomeLayout.aspx. For more information about the relationship of master pages and page layouts to site pages, see Overview of
the SharePoint 2013 page model.
This topic shows you how to customize a page layout by updating the starter stores welcome page layout.
To update a page layout

1. Open a web browser and navigate to the Welcome page for the starter store. Typically, the URL for the Welcome page resembles the following:
Note
Observe the behavior of the page. A slide show cycles through three pictures representing product categories. At the top left-hand side of the page, you can see
the Contoso logo.
2. Open another web browser on a computer where you are logged in using the administrative account for SharePoint.
3. Navigate to the Site Settings page of the store. Use port 40003 and sign in with administrative credentials. The link to the Site Settings page is typically found at a
URL that resembles the following:
http://<computer-name>:40003/sites/RetailPublishingPortal/_layouts/15/settings.aspx
Tip
Add this page to your Favorites to make it easy to return to it in the future.
4. Click Master pages and page layouts in Web Designer Galleries to view a list of files in the Master Page Gallery page.
5. Right-click a file that you want to edit, such as WelcomeLayout.aspx, and then click Check Out.
6. Right-click the file and then click Download a Copy.
7. Edit the file by using Visual Studio or another editor. For example, the following code from WelcomeLayout.aspx specifies the names of the tabs on the Welcome
page.
<div class="msax-tabs">
<ul>
<li><a onclick="return
false;"
false;"
false;"
false;"
href="#tabs-1">Customer favorites</a></li>
href="#tabs-2">Staff recommendations</a></li>
href="#tabs-3">Shop by brand</a></li>
href="#tabs-4">Clearance items</a></li>
8. Change the names of the tabs by editing the text. You can use the following code to change the names of the tabs:
<div class="msax-tabs">
<ul>
false;"
false;"
false;"
false;"
href="#tabs-1">Your favorites</a></li>
href="#tabs-2">Our recommendations</a></li>
href="#tabs-3">Shop by brand</a></li>
href="#tabs-4">Special offers</a></li>
9. To upload the file and add your changes to the site, click Upload Document on the Files ribbon.
Tip
This procedure illustrates one way of changing master pages and page layouts for the online starter store. For more information about how to use Microsoft
SharePoint Server 2013 to modify the visual site design, see Develop the site design in SharePoint 2013.
Note
You can edit the page layout files directly by mapping a network drive. For more information, see Map a network drive to the SharePoint 2013 files for online stores.
See also
How to: Create a page layout in SharePoint Server 2013
2014 Microsoft
Customize the appearance and behavior of site pages [AX 2012]

You can customize the visual design of the Microsoft Dynamics AX 2012 R2 starter store by modifying certain types of files. Cascading style sheet (CSS) provide the page layouts
with styling and formatting. For example, you can change the color of elements on store pages by making modifications to CSS files. For more information, see Walkthrough:
Creating and Modifying a CSS File.
The Welcome page for the starter store contains a slide show with a counter. This topic shows you how to modify the CSS file for the Welcome page to change the colors that
highlight the current slide number.
Note
You can also change the appearance and behavior of the site by using JavaScript. JavaScript files provide the page layouts with client-side scripting functionality. For more
information, see How to: Complete basic operations using JavaScript library code in SharePoint 2013. Typically, files that contain JavaScript for the starter store pages are
found in a path that resembles the following:
\ProgramFiles\CommonFiles\MicrosoftShared\WebServerExtensions\15\TEMPLATE\LAYOUTS\Storefront\js
For more information about how to modify JavaScript in the starter store, see Customize the functionality of an online store.
To update the CSS file for the Welcome Page to change the color of the slide counter
1. Open a web browser and open the Welcome page for the starter store. Typically, the URL for the Welcome page resembles the following:
Note
Observe the behavior of the page. A slide show cycles through three pictures representing product categories. In the lower-right-hand corner of the slides, a counter
displays the current slide number. The following illustration shows the counter displaying the slide number in the original colors of gray and white.
2. Navigate to the folders on the computer where the online starter store is deployed. Typically, the path for the folder location for CSS files resembles the following:
\ProgramFiles\CommonFiles\MicrosoftShared\WebServerExtensions\15\TEMPLATE\LAYOUTS\1033\STYLES\Storefront
3. Open the Welcome.css file. You can use Visual Studio or any editor that you prefer. For example, consider the slide show on the Welcome page. That is the first page that
you see when you access the store on port 40002. The indicator displays the number of the current slide. In the starter store, these are numbered 1, 2, and 3, and the
numbers are white on a black background.
The following code from Welcome.css shows initial values for color and border:
.msax-reel_paging a {
padding: 5px;
text-decoration: none;
color: #fff;
}
.msax-reel_paging a.active {
font-weight: bold;
background: #1c2023;
border: 1px solid #101315;
-moz-border-radius: 3px;
-khtml-border-radius: 3px;
-webkit-border-radius: 3px;
}
The following table lists the original colors that are used.
Parameter
Element
Color Code
Color
color:
Text
#fff
White
border:
Border for text
#101315
Dark grey
4. Modify the values for color and border as shown in the following code to create a display that has text in red (#f00) and highlights the current slide number in green
(#3c8a3c):
.msax-reel_paging a {
padding: 5px;
text-decoration: none;
color: #f00;
}
.msax-reel_paging a.active {
font-weight: bold;
background: #1c2023;
border: 1px solid #3c8a3c;
-moz-border-radius: 3px;
-khtml-border-radius: 3px;
-webkit-border-radius: 3px;
}
The following table lists the new colors you have entered.
Parameter
Element
Color Code
Color
color:
Text
#f00
Red
border:
Border for text
#3c8a3c
Green
5. Save and close the file.

The following illustration shows the slide show counter with colors corresponding to the changes you made.
See also
Cascading style sheet (CSS) files for Retail online store
Overview of the SharePoint 2013 page model
JavaScript API reference for SharePoint 2013
Execute basic tasks using the JavaScript object model
2014 Microsoft
Cascading style sheet (CSS) files for Retail online store [AX 2012]
Cascading style sheet (CSS) provide the page layouts with styling and formatting in a Microsoft Dynamics AX 2012 R2 online store. For a typical installation, the path for the
folder location of the CSS files resembles the following:
\ProgramFiles\CommonFiles\MicrosoftShared\WebServerExtensions\15\TEMPLATE\LAYOUTS\1033\STYLES\Storefront
The following table lists the cascading style sheets used in the online starter store.
Cascading Style Sheet
Description
AddressEdit.css
Defines the formatting for the components that appear on the AddressEdit page.
AssociateCustomer.css
Defines the formatting for the components that appear on AssociateCustomer page.
CheckoutConfirm.css
Defines the formatting for the components that appear on CheckoutConfirm page.
Control_ProductVariant.css
Defines the formatting that applies to the control selected for the Item Details display template.
Core.css
Defines global formatting that applies to all pages and user interface components of the starter store.
CustomerEdit.css
Defines the formatting for the components that appear on Login page.
Item_ProductDetails.css
Defines the formatting for the components that appear on ProductDetails page.
Item_ProductGallery.css
Defines the formatting for the components that appear on ProductGallery page.
Item_Recommended
Defines the formatting that applies to the Item_Recommended display template that is used by the following web parts: Related Products,
Customer Favorites, Shop By Brand, Clearance items.
Login.css
Defines the formatting for the components that appear on Login page.
MyAccount.css
Defines the formatting for the components that appear on MyAccount page.
OrderCheckout.css
Defines the formatting for the components that appear on Checkout page.
OrderDetails.css
Defines the formatting for the components that appear on OrderDetails page.
OrderHistory.css
Defines the formatting for the components that appear on OrderHistory page.
ProgressBar.css
Defines the formatting for the checkout progress bar on the OrderCheckout page that is displayed for Shipping information, Billing
Information, and Review.
Register.css
Defines the formatting for the components that appear on the page that enables a user to register a new account.
Reset.css
Resets some of the default HTML formatting defined in Core.css on the master page in order to make the pages as browser-independent
as possible.
ShoppingCart.css
Defines the formatting for the components that appear on ShoppingCart page.
Tab.css
Defines the formatting for the tab control that appears on Quickview and ProductDetails pages.
Welcome.css
Defines the formatting for the components that appear on Welcome page.
See also
How to: Create a page layout in SharePoint 2013
2014 Microsoft
Customize the functionality of an online store [AX 2012]

The Microsoft Dynamics AX 2012 R2 Retail starter store is a site built by using the commerce runtime (CRT) and the new site authoring and publishing model in Microsoft
SharePoint Server 2013. You can use the Retail starter store as a basis for developing your own online store by calling JavaScript methods for supported events. The
starter store includes events that correspond to certain shopping activities such as add item to shopping cart and remove item from shopping cart. You can use these events
to add functionality of your own, in a way that resembles using the jQuery eventing model. You turn your custom functionality on and off by using methods such as
OnAddToCart and OffAddToCart. For example, you can change the message that is displayed when an item is added to the shopping cart.
This topic shows you how to change the message that is displayed when an item is added to the shopping cart. It also lists the methods for the types of events that are
available to modify the behavior of the starter store.
To change the message displayed when an item is added to the shopping cart
1. Open a web browser and move to the Welcome page for the starter store. Typically, the URL for the Welcome page resembles the following:
Add some items to the shopping cart.
Note
Observe the behavior of the page. When you click Add to cart under one of the items, a popup is displayed with the message Updating shopping cart.
2. Navigate to the folders on the computer where the online starter store is deployed. Typically, files that contain JavaScript for the starter store pages are found in a
path that resembles the following:
\ProgramFiles\CommonFiles\MicrosoftShared\WebServerExtensions\15\TEMPLATE\LAYOUTS\Storefront\js
3. Open the file Storefront.js. You can use Visual Studio or any editor that you prefer.
4. Find the line that contains msaxServices.OnAddToCart. The following example shows how to modify the code after line 170.
msaxServices.OnAddToCart(function () {
// msaxPopupOverlay.show('Updating shopping cart...');
alert('Adding to cart...');
});
5. Refresh the store pages and add an item to the cart. You see the message Adding to cart in the message window. Click Ok to continue.
Extending the Functionality of the Online Store

The starter store is designed to be extensible at many points in the shopping experience. For example, you can add the following JavaScript code in any JavaScript file
for a page that includes the shopping cart objects. The following example causes a message to display before an item is added to the shopping cart.
var addToCartVM = new Microsoft.Dynamics.Retail.SharePoint.Web.UI.ViewModel.AddToCartViewModel(services, $view);

// Performed before AddToCart
addToCartVM.OnAddToCart(function (event) {
alert('Adding item to cart');
});
Method Names for Supported Events and Objects

The following tables list the method names and objects available for turning on and off functionality for supported events in the view models for the starter store.
Typically, the JavaScript code for the view models can be found in a path that resembles the following, after you map a drive to the SharePoint Server 2013 files:
Z:\Scripts\ViewModel
The following table lists methods for Microsoft.Dynamics.Retail.SharePoint.Web.UI.ViewModel.AddToCartViewModel. The code for this view model is found in the
file AddToCart.js.
Method Name
Data Object Available
Description
OnAddToCart, OffAddToCart
None
Raised on a call to AddToCart.
OnAddToCartSuccess, OffAddToCartSuccess
ShoppingCart
Raised after a successful return from AddToCart.
OnAddToCartFailure, OffAddToCartFailure
Raised if no response is returned from a call to AddToCart.
None
The following table lists methods for the Microsoft.Dynamics.Retail.SharePoint.Web.UI.ViewModel.CheckoutViewModel. The code for this view model is found in
the file Checkout.js.
Method Name
Data Object Available
Description
OnCheckout, OffCheckout
None
Raised on a call to the Checkout method.
OnNoItemCheckout, OffNoItemCheckout
None
Raised on a successful response to the AddToCart method.
The following table lists methods for the Microsoft.Dynamics.Retail.SharePoint.Web.UI.ViewModel.ShoppingCartViewModel. The code for this view model is
found in the file ShoppingCart.js.
Method Name
Data Objects Available
Description
OnBeforeRender, OffBeforeRender
ShoppingCart
Raised on a call to the Render method of the shopping cart view.
OnAfterRender, OffAfterRender
ShoppingCart
Raised after execution of the Render method of the shopping cart view.
OnRemoveFromCart, OffRemoveFromCart
ShoppingCart
Raised on a call to the RemoveFromTCart method.
OnUpdateQuantity, OffUpdateQuantity
ShoppingCart
Raised on a call to the UpdateQuantitymethod.
The following table lists methods for the Microsoft.Dynamics.Retail.SharePoint.Web.UI.ViewModel.MiniShoppingCartViewModel. The code for this view model is
found in the file MiniShoppingCart.js.
Method Names
Data Objects Available
Description
OnBeforeRender, OffBeforeRender
ShoppingCart
Raised on a call to the Render method of the MiniShoppingCartViewModel.
OnAfterRender, OffAfterRender
ShoppingCart
Raised after execution of the Render method of the MiniShoppingCartViewModel.
OnShow, OffShow
None
Raised on a call to the Show method of the MiniShoppingCartViewModel.
OnHide, OffHide
None
Raised on a call to the Hide method of the MiniShoppingCartViewModel.
See also
How to use F12 Developer Tools to Debug your Webpages
2014 Microsoft
Customize display templates for an online store [AX 2012]

The Retail starter store is a site built by using the commerce runtime (CRT) and the new site authoring and publishing model in Microsoft SharePoint Server 2013. You can
use the Retail starter store as a basis for developing your own online store. To customize the display of items from your catalog, you can modify the display templates for
the search-driven Web Parts. For more information, see the section Search-driven Web Parts and display templates in Overview of the SharePoint 2013 page model.
You can modify any of the display templates that are found in the folder _catalogs\masterpage\Display Templates\Content Web Parts. This folder is available after
you Map a network drive to the SharePoint Server 2013 files for the starter store.
The following table describes three display templates that you can modify.
File Name
Description
Contoso_Default_Item_ProductDetails.html
Display template for the Product Details page.
Contoso_Default_Item_ProductQuickView.html
Display template for the Product QuickView page.
Contoso_Default_Item_ProductGallery
Display template for the Product Gallery page.
To modify a display template

1. Observe the web site behavior when you click on a product. For example, click Electronics, and then click a product name under one of the cameras to display the
Product Details page.
2. Map a network drive to the SharePoint Server 2013 files for the starter store.
3. Open the Contoso_Default_Item_ProductDetails.html file in the _catalogs\masterpage\Display Templates\Content Web Parts folder.
4. Find the text $resource(ItemNumber). ItemNumber refers to a string defined in the resource file, StorefrontResources.js.
5. Open the StorefrontResources.js file.
6. Find the text ItemNumber:ITEMNUMBER:, and change the text to read ItemNumber:ITEMSERIALNUMBER:.
8. Refresh the Product Details page in your browser and observe the changed text.
See also
Display template reference in SharePoint Server 2013
How to: Create a display template in SharePoint Server 2013
2014 Microsoft
Debug X++ Code for Retail [AX 2012]

You can use the X++ debugger to debug from Microsoft Dynamics AX for Retail POS to Commerce Data Exchange: Real-time Service to Microsoft Dynamics AX, or from
commerce runtime to Real-time Service to Microsoft Dynamics AX. Perform the following steps to debug code that runs on the client:
Create a local client configuration.

Create a Business Connector configuration.
Update the Business Connector configuration in the registry editor.
Then you can set breakpoints in your X++ code and begin debugging.
Caution
To debug code that runs on the server, you must also configure debugging on the AOS server. For more information, see How to: Debug X++ Code Running in .NET
Business Connector.
To Create a Local Client Configuration

1. Open Microsoft Dynamics AX 2012 Configuration.
2. In Configuration Target, select Local client.
3. Click Manage, and then click Create configuration
4. Enter a configuration name. For example, DebugClient.
5. Select Active configuration, and then click OK.
6. Click the Developer tab. Select Enable user breakpoints to debug code in the Business Connector.
To Create a Business Connector Configuration

1. If you are not already in the Microsoft Dynamics AX Configuration Utility form, open Microsoft Dynamics AX 2012 Configuration.
2. In Configuration Target, select Business Connector (non-interactive use only).
3. Click Manage, and then click Create configuration
4. Enter a configuration name. For example, DebugBCNet.
5. Select Active configuration, and then click OK.
6. Click the Developer tab. Select Enable user breakpoints to debug code in the Business Connector.
7. Close the utility.
To Update the Registry Editor

1. Open Windows Command Processor.
2. Enter regedit.exe.
3. Right-click the key that corresponds to the Business Connector configuration you created in the previous procedure, point to New, and then click String value.
Note
For example, HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Dynamics\6.0\Configuration\DebugBCNet.
4. Right-click the new value, and then click Rename. Enter debug_across_os_session.
5. Double-click debug_across_os_session.
6. In Value data, enter 1. Click OK.
7. In Windows Command Processor, enter IISReset, and then press Enter.
See also
Microsoft Dynamics AX Debugger
How to: Debug X++ Code Running in .NET Business Connector
Debug code in a Retail online sample store [AX 2012]

The sample online stores for Retail in Microsoft Dynamics AX 2012 R3 use SharePoint 2013 and code that is found in the Retail SDK. You can debug the sample online
store code for the SharePoint pages in a browser window or by using Visual Studio. You use the F12 developer tools to debug code in a browser window. In Visual Studio,
you can attach the worker process to debug your code.
Preparation for debugging

You must recompile the source code found in the Retail SDK and redeploy it before you can debug the code for the sample Retail online stores.
Debugging Retail online store site pages

The Retail SDK contains source code for the sample online stores. For more information, see Install Retail SDK (Retail POS Plug-ins) and Retail SDK.
Debugging in a browser window

You can debug test, and speed up your webpages by using the F12 developer tools. Open the tools by pressing F12 or by clicking F12 developer tools on the Tools
menu in Internet Explorer. For more information, see Using the F12 developer tools.
Debugging in Visual Studio

To step through code in the online store pages, you must attach the worker process w3wp.exe that runs ASP.NET applications within IIS. To find the worker process,
open IIS Manager, select the server name and click Worker Processes in the IIS section of the Features View pane. Then find the worker process that matches the
Application Pool for the site. You can use IIS to find the name of the Application Pool for the site, and determine the user that the Application Pool runs under.
2014 Microsoft
Update the Publishing Job Configuration [AX 2012]

The Microsoft Dynamics AX for Retail publishing job has parameters that are stored in a .NET application configuration file. The file is loaded at runtime each time the job
is started. Before the file is called by the publishing job code, it must be extracted from your SharePoint configuration database, where it is persisted in serialized form.
You can update the configuration file before Microsoft Dynamics AX is installed by opening the RetailPublishingJob.App.config file and modifying its contents. After you
deploy Microsoft Dynamics AX, the configuration file will be persisted in the configuration database and will be used each time the publishing job runs.
Note
Microsoft Dynamics AX 2012 R3 has a tool in the Retail SDK that you can use to update the publishing job configuration. For more information, see Microsoft Dynamics
AX for Retail online channel tools.
If you update the configuration file after Microsoft Dynamics AX is installed, you must read the configuration file from the configuration database, update it, and then save
it.
Note
The maximum number of listings that the publishing job can retrieve in one page while querying the database (one trip to the database) is 2,100. If you modify your
settings to retrieve more listings than the maximum, the job will fail.
Settings of the Publishing Job

The following example shows XML that contains the settings of the publishing job:
<jobConfiguration CategoriesPageSize="200"
ProductAttributesPageSize="200"
CRTListingPageSize="2000"
ChannelListingPageSize="500"
ListingMapPageSize="10000"
ForceTimingInfoLogging ="false"
DefaultUncategorizedListName ="UncategorizedList"
MaxListLengthForInitialPublishing ="20000"
MaxListLengthForIncrementalPublishing ="0"
MaxListFieldCount ="200"
ListingTitleAttributeKey="Productname"
MaxCatalogSizePerPublishingIteration="0"
MaxActiveCrawlerWaitTime="0">
<TypeMappings>
<add Name="Specification" Value="Note"/>
<add Name="Features" Value="Note" />
</TypeMappings>
<PartitioningSchema>
</PartitioningSchema>
</jobConfiguration>
Reading the Publishing Job Configuration

The job configuration is persisted in the configuration database with the ID 920EEF5F-8BB4-4855-AB4A-7D3C28919F13.
The following code demonstrates how to read the configuration file.
Guid JobSettingsId = new Guid("920EEF5F-8BB4-4855-AB4A-7D3C28919F13");

RetailPublishingJobSettings currentSettings = (RetailPublishingJobSettings)SPFarm.Local.GetObject(JobSettingsId);
This code returns an instance of the RetailPublishingJobSettings class, which is defined in the Microsoft.Dynamics.Retail.SP.PublishingConnector.dll assembly
and has two public fields:
AppConfigString
CommerceRuntimeConfigString
The AppConfigString field is the Commerce Runtime (CRT) configuration that you might want to update if you are customizing the CRT. The
CommerceRuntimeConfigString field contains the XML configuration file that is described above.
Updating the Publishing Job Configuration

The following code demonstrates how to read, modify, and save the configuration file.
RetailPublishingJobSettings settings = (RetailPublishingJobSettings)SPFarm.Local.GetObject(JobSettingsId);

// Delete old settings.
settings.Delete();
// Modify original settings.
settings = new RetailPublishingJobSettings(SPFarm.Local.TimerService, JobSettingsId)
{
// Typically you would use XML parsing to find and modify correct attribute.
AppConfigString = settings.AppConfigString.Replace(@"""UncategorizedList""", @"""CustomList"""),
CommerceRuntimeConfigString = settings.CommerceRuntimeConfigString
};
settings.Update();
The configuration file that contains the jobSettings section also contains a section called connectionStrings. The connectionStrings section contains a connection
string called CommerceRuntimeConnectionString that points to the CRT database. You can use the same procedure of reading, modifying, and saving the configuration
to update the connection string.
2014 Microsoft
Create a URL for search engine optimization (SEO) in a Retail

online store [AX 2012]
Note
This topic applies only to installations of Retail in Microsoft Dynamics AX 2012 R2.
To improve search engine optimization (SEO) in a Retail online store, you can add product names to the URLs on your site pages. Search engines use keywords in URLs to
return search results. When customers type product names into a search engine, they will see your store pages returned if you have included those product titles in your
catalog URLs.
To create these user-friendly URLs you set values on the Catalog Source Settings page in the Site Settings area in SharePoint.
Create a user-friendly URL that contains the product name of an item from the catalog in the Contoso
online sample store
The following procedure describes how to include a product name in a URL.
To create a URL that contains a product title

1. Visit http://<your SharePoint server name>:40003/sites/RetailPublishingPortal/_layouts/15/ManageCatalogSources.aspx.
2. Click the name of the catalog from the list under Catalog Name. If you deployed the Contoso online sample store without customizations, the catalog name may
resemble the following:
Retail Product Catalog UncategorizedList_000
3. On the Catalog Source Settings page, set Catalog Item URL Behavior to Make URLs relative to this site.
4. In the Catalog Item URL Format area, select Construct a URL format from catalog properties.
5. Add the desired Available Fields to the Selected Fields list.
For example, select the Title field from the list of Available Fields and then click Add. Move Title to the top of the list.
6. Click Ok to save your changes.
Notice that for the URL displayed earlier in this section the Ok button changes to include the fields you have selected. For example, you can select Title and move
it to the top of the list of Selected Fields in the Contoso online sample store. The original URL has the elements in the following example.
http://< your SharePoint server
name>:40003/sites/RetailPublishingPortal/TermRoot/Term/[ProductCatalogGroupNumberOWSTEXT]/[ProductCatalogItemNumberOWSTEXT]
After moving Title to the top of the list, the URL contains the value for Title (in other words, the product name) as shown in the following example.
http:// <your SharePoint server name>:40003/sites/RetailPublishing
Portal/TermRoot/Term/Title/[ProductCatalogGroupNumberOWSTEXT]/[ProductCatalogItemNumberOWSTEXT]
Note
The numbers for ProductCatalogGroupNumber and ProductCatalogItemNumber must be retained at the end of the URL string to make sure that the product
can be uniquely identified.
7. Close and re-open the browser to view your changes in the URLs for the products.
Note
Be sure to specify the site by using portal number 40002, in order to view what an end-user customer sees. For example, you might see a URL that resembles
the following example to locate the item that has the title Contoso Multi-line phone 20m30: Http:// <your-SharePoint-server-name>:40002/
sites/RetailPublishingPortal/phones/home-and-office-phones/Contoso%20Multi-line%20phones%20M30/22565424432/22565424433.
If you want to add other fields to the Available Fields list, you can create additional attributes for the catalog. After you add the attributes to the channel, you republish
the channel and the catalog. For more information about how to set up attributes, see Set up an online store.
See also
Search Engine Optimization (SEO) in SharePoint Server 2013
White Paper: Optimizing SharePoint Server 2013 websites for Internet search engines
Components of the Retail online sample store [AX 2012]

You can modify every component of the Retail online sample store that is available with Microsoft Dynamics AX 2012 R3. You can customize the products that are available
in the store, you can modify the data elements that are displayed, and you can customize the appearance and behavior of site pages.
The following table describes some of the common customizations for Retail online sample stores.
What you can customize
Link to documentation
Change the products that are available in the store
Configure online store products
Add a logon provider, such as Facebook
Modify the appearance and behavior of store pages
Extend the online store to expose additional data from the AX 2012 R3
database.
Walkthrough: Adding a table for customer preferences to the AX 2012 database

Walkthrough: Extending the CRT to add customer preference data for Retail clients
Walkthrough: Extending retail data distribution infrastructure for customer
preferences
Walkthrough: Adding customer preferences to the Retail online sample store
Reference documentation for elements of the Retail online sample store site pages
Source code for the online sample stores is found in the Retail Software Development Kit (SDK). For more information, see Retail SDK.
This section contains reference documentation for the elements that make up the online store pages.
Wish list
Shopping Cart
See also
Getting started with customizing the Retail online sample store
Retail online store publishing architecture
2014 Microsoft
Authenticating users in Retail online sample stores [AX 2012]

The Microsoft Dynamics AX 2012 for Retail online sample stores authenticate customers and site administrators by using the two authentication types supported by
Microsoft SharePoint Server 2013:
Forms-based authentication for customers.

Windows classic mode authentication for site administrators.
For more information about Windows and forms-based authentication with SharePoint Server 2013, see Authentication overview for SharePoint 2013 and Authentication,
authorization, and security in SharePoint 2013.
Configuration and authentication

Site administrators configure how site users are authenticated by specifying publishing portal settings in PowerShell deployment scripts. For more information, see Install
a Microsoft Dynamics AX Retail online store (e-commerce). The PowerShell deployment scripts create web applications in Internet Information Services (IIS) and
SharePoint. For example, the deployment scripts can create the following two web applications for the Contoso sample online store:
For SharePoint, the web application is called Out of box Store front Public 1.
For IIS, the web application is called RetailC2WebApplication-1.
The deployment scripts also create site collections on the SharePoint web application. The default settings for the site collections configure port 40003 for site
administrators and port 40002 for customers. For example, the Contoso online sample store can authenticate users who access the site URLs as shown in the following
table.
URL
Authentication method
http://
computername:40003/sites/RetailPublishingPortal
Windows authentication. When you sign in your current Windows user ID is used for authentication.
http://
computername:40002/sites/RetailPublishingPortal
Forms-based authentication that includes external logon providers such as Facebook. Users may remain
anonymous if they decide not to log on.
Authenticating customers by using forms-based authentication

The Retail online sample stores use three types of authentication for store customers. Customers can remain anonymous, create a new user ID, or log on as a returning
user. Anonymous users may purchase products, but their identifying information and credentials are not stored permanently. When a customer creates a new user ID, a
customer record is created in the CustTable table in AX 2012. Credentials for returning customers are validated by using forms-based authentication.
When you install and deploy the sample sites, you configure the default validation for customers credentials. You can configure the SharePoint database as the
membership and role provider or you can configure Facebook as an external logon provider. The Dynamics custom claims provider implements the mapping of a
customer in the AX 2012 database to a customer of the Retail online sample store.
Authentication process
The following diagram illustrates the components and databases involved in authenticating a user who signs in to the Contoso site on port 40002.
The following numbered steps describe the processes in the diagram.
1. The user clicks Sign In on the store home page or accesses a page that requires authentication.
2. The user is redirected to the Login.aspx page.
3. The user enters an e-mail address and password. Data is sent to the SharePoint Secure Token Service (STS). The STS calls the forms-based identity provider,
which is based on the ASP.NET forms-base authentication provider and the AX 2012 Retail custom claims provider.
4. The identity provider uses the forms-based membership database SpFBA to validate the user name and password.
5. The STS may invoke other identity providers, such as Facebook.
6. After authentication, the Dynamics custom claims provider queries the customer mapping database SpSQLAuthZ, returns the AX 2012 customer ID for the user,
and adds it to the claim set.
7. The STS returns the claim set back to the page.
8. The page is sent to the users browser.
Authenticating a new customer

A new customer who does not decide to register an account receives a temporary token that SharePoint uses to authenticate the session. The new customer can check
out as a guest or click Register a New Account on the Sign In page to create a customer record in the AX 2012 database. Registering a new account sets up the
user as a customer in the AX 2012 database and creates a mapping between the customers credentials and the record for the customer in AX 2012.
Authenticating a returning customer

After a returning customer is authenticated, the custom claims provider adds the customer information from the AX 2012 database to the claim.
Extending user authentication by adding a logon provider

You can configure Facebook as an external logon provider when you install the Retail online store. Source code for integrating Facebook authentication is provided in
the Retail SDK as an example for extending user authentication. To find the sample code, open the file Retail SDK\Online Channel\Storefront.sln in Visual Studio. The
source code for Facebook integration is found in the SharePoint.Web.Common project under the Facebook folder.
See also
Plan for user authentication methods in SharePoint 2013
Incoming claims: Signing into SharePoint 2013
Forms authentication in ASP.NET
2014 Microsoft
Walkthrough: Adding a table for customer preferences to the AX

2012 database [AX 2012]
In this walkthrough you create a new table in Microsoft Dynamics AX 2012 to capture additional customer data in a retail channel. The new table is called
RetailCustPreferences and it is related to the CustTable so that each customer has the new fields for marketing preferences. You modify the customer form to display
and add values to the field in the new table.
Prerequisites
Online Store
Create the RetailCustPreferences table
Modern Point of Sale
Add the new fields to the Customer form
Prerequisites
These walkthroughs illustrate adding a field to a retail channel that enables customers to opt in to receive special offers by email. In this scenario, the retailer wants to
indicate whether customers wish to receive email about special offers, either in an online store or in a modern POS client. The walkthroughs should be completed in the
following order:
1. Walkthrough: Adding a table for customer preferences to the AX 2012 database

2. Walkthrough: Extending the CRT to add customer preference data for Retail clients
3. Walkthrough: Extending retail data distribution infrastructure for customer preferences
4. Walkthrough: Adding customer preferences to the Retail online sample store (online store only)
In the first walkthrough, you create a table to store the customer preferences. The following links provide background information about creating a new table.
How to: Create Tables

Table Properties
Defining Table Relations
How to: Add a Relation to a Table
Best Practices for Table Relations
Create the RetailCustPreferences table

You use the Data Dictionary in the AOT to add a new table.
To add a new table

1. In the Microsoft Dynamics AX client, press CTRL + D to open the development workspace.
2. In the AOT, expand DataDictionary, right-click the Tables node, and then click New Table.
3. Right-click the new table name and then click Properties.
4. Set the Name property to RetailCustPreferences and then press Ctrl+S to save the new table.
5. Expand the new RetailCustPreferences node, right-click the Fields node, click New, and then click Enum.
6. Specify the following properties for the new field:
Property
Value
Name
EmailOptIn
Label
Email Opt In
EnumType
NoYes
7. Press Ctrl+S to save your changes.
To create the relation on the new table

1. In the AOT, expand the Data Dictionary node, expand the Tables node and then expand the RetailCustPreferences node.
2. Right-click Relations and then click New Relation.
3. Right-click the new relation and then click Properties.
4. Set the values for the properties as shown in the following table.
Property
Value
Name
CustTable
Table
CustTable
Validate
Yes
EntityRelationshipRole
blank
RelatedTableCardinality
ExactlyOne
Cardinality
ZeroOne
RelationshipType
Composition
UseDefaultRoleNames
Yes
RelatedTableRole
blank
Role
blank
EDTRelation
No
5. Right-click the new relation, select New, click ForeignKey, and then click PrimaryKey based.
Notice the CustTable field is added for the RetailCustPreferences table in the Fields node, and the relation is added in the Relations node under CustTable.
6. Right-click the new relation under CustTable and then click Properties.
7. Set the SourceEDT property to CustAccount.
8. Under the Fields node, right-click CustTable and then click Properties.
9. Set the properties as shown in the following table.
Property
Value
Name
AccountNum
ExtendedDataType
CustAccount
10. Right-click RetailCustPreferences and then click Save.

11. Right-click RetailCustPreferences and then click Sychronize to apply your changes to the database.
12. Right-click RetailCustPreferences and then click Compile.
13. To view the contents of the table and add data, you can right-click ISVCustomerMarketingPreferences in the Tables node, click Add-Ins, and then click Table
Browser.
14. Close the developer workspace and any Microsoft Dynamics AX clients.
Add the new fields to the Customer form

Adding the fields from the new table to the Customer form enables adding data for a test customer by using the Microsoft Dynamics AX client. You add the new table
to the Datasource node of the CustTable form.
To add a field to the Customer form

1. Open the Microsoft Dynamics AX developer workspace.
2. In the AOT, expand the Forms node and then expand the CustTable node.
3. Right-click Data Sources and then click New Data Source.
4. Right-click the new data source and then click Properties.

5. Set the properties as shown in the following table.
Property
Value
Name
RetailCustPreferences
Table
Index
blank
CounterField
blank
AllowCheck
Yes
AllowEdit
Yes
AllowCreate
Yes
AllowDelete
Yes
StartPosition
First
AutoSearch
Yes
AutoNotify
Yes
AutoQuery
Yes
CrossCompanyAutoQuery
No
OnlyFetchActive
No
JoinSource
CustTable
LinkType
OuterJoin
DelayActive
Yes
InsertAtEnd
Yes
InsertIfEmpty
Yes
6. Right-click CustTable in the Forms node and then click Save.

7. Expand the Designs node, the Design node, the Tab:Tab node, and then the TabPage:TabPageDetails node.
8. Expand the Tab:TabHeader node to view the FastTab categories.
9. Right-click the TabPage:Retail node, select New Control, and then click Group.
10. Set the Name property for the new group to CustomerPreference and set the Caption property to Customer preferences.
11. Right-click the Group:CustomerPreference node, select New Control and then click CheckBox. Set the following properties.
Property
Value
Name
RetailCustomerPreferences _EmailOptIn
DataSource
DataField
EmailOptIn
Label
Email Opt In
12. Right-click CustTable in the Forms node, click Save, and then click Compile. You can disregard the Best practices messages.
13. Right-click CustTable and then click Open to view the form. Click Edit on the Action pane.
14. Click Retail to open the Retail FastTab.
15. Now, we must write code to populate the Customer account.
a. In the AOT, open the Forms node and navigate to the CustTable form.
b. Right-click CustTable, click View Code.
c. Click CustTable:validateWrite. Add the following line of code to the block before the ret = super(); statement: retailCustPreferences.AccountNum
Walkthrough: Adding customer preferences to the Retail online

sample store [AX 2012]
To make the new customer preference data available in SharePoint pages, you must modify code in Retail SDK\Online Channel\Storefront\Storefront.sln. First, you add
code to make the new fields available in the data model and the view model. Then you modify the web controls, and then you modify the store pages to enable display,
entry, and modification of the new fields. Finally, you rebuild and redeploy the solution.
You make the new field available on the Customer control, which is included on the Account page and the Edit Profile. On the Account page, the field is read-only.
Customers can edit the field on the EditProfile page.
Prerequisites
Online Store
Make the new fields available in the data model and the view model
Make changes to the controller
Make the new fields visible on the site pages
Add code to ControlResources.Designer.cs
Add text to ControlResources.resx
Prerequisites
These walkthroughs illustrate adding a field to a retail channel that enables customers to opt in to receive special offers by email. In this scenario, the retailer wants to
indicate whether customers wish to receive email about special offers, either in an online store or in a modern POS client. The walkthroughs should be completed in the
following order:
1. Walkthrough: Adding a table for customer preferences to the AX 2012 database

2. Walkthrough: Extending the CRT to add customer preference data for Retail clients
3. Walkthrough: Extending retail data distribution infrastructure for customer preferences
4. Walkthrough: Adding customer preferences to the Retail online sample store (online store only)
Make the new fields available in the data model and the view model
In the SharePoint.Web.Services project of the Storefront.sln solution, you modify ViewModel\Customer.cs and ObjectModel\Customermapper.cs. You modify the
Javascript files Customer.js and CustomerDisplay.js inStorefront\Scripts\Scripts\ViewModel.
To modify the view model

1. Open the Retail SDK\Online channel folder and open Storefront.sln. and navigate to Modify Customer.cs in SharePoint.Web.Services\ViewModel\Customer.cs by
adding the following code at the end of the file:
2. Open Customer.cs in SharePoint.Web.Services\ViewModel.
3. Add the following code at the end of the file:
[DataMember]
public Enum EmailOptIn { get; set; }
To map the new field to the object model

1. You modify SharePoint.Web.Services/ObjectModel/ CustomerMapper.cs to create a mapping between the new fields in the data model and the view model.
2. You add the new fields to ConvertToViewModel and ConvertToDataModel methods.
Add the following lines of code to the ConvertToViewModel method after the first If statement.
bool emailOptIn = false; /// NEW Code

var emailOptInExtensionProperty = customer.ExtensionProperties.Where(c => c.Key == "EMAILOPTIN").FirstOrDefault();
if (emailOptInExtensionProperty != null)
{
int intEmailOptIn = (int)emailOptInExtensionProperty.Value.GetPropertyValue(); // NEW Code
emailOptIn = intEmailOptIn == 0 ? false : true;
}
3. Add the following code after the statement LoyaltyCardNumbercustomer.LoyaltyCardNumber,.
EmailOptIn = emailOptIn // NEW Code
The following example shows the ConvertToViewModel method after adding the code.
internal static ViewModel.Customer ConvertToViewModel(DataModel.Customer customer)

{
if (customer == null)
{
throw new ArgumentNullException("customer");
}
bool emailOptIn = false; /// NEW Code
var emailOptInExtensionProperty = customer.ExtensionProperties.Where(c => c.Key == "EMAILOPTIN").FirstOrDefault();
if (emailOptInExtensionProperty != null)
{
int intEmailOptIn = (int)emailOptInExtensionProperty.Value.GetPropertyValue(); // NEW Code
emailOptIn = intEmailOptIn == 0 ? false : true;
}
ViewModel.Customer vmCustomer = new ViewModel.Customer()
{
AccountNumber = customer.AccountNumber,
Addresses = ConvertToViewModel(customer, customer.Addresses),
Email = customer.Email,
FirstName = customer.FirstName,
LastName = customer.LastName,
MiddleName = customer.MiddleName,
Phone = customer.Phone,
PhoneExt = customer.PhoneExt,
RecordId = customer.RecordId,
Url = customer.Url,
PrimaryAddress = AddressMapper.ConvertToViewModel(customer.GetPrimaryAddress(), customer),
LoyaltyCardNumber = customer.LoyaltyCardNumber,
EmailOptIn = emailOptIn // NEW Code
};
return vmCustomer;
}
4. Add the following line of code to the UpdateDataModel method.
dataModelCustomer["EMAILOPTIN"] = Convert.ToInt64(customer.EmailOptIn); ///NEW Code
The following example shows where the line is added.
internal static DataModel.Customer UpdateDataModel(DataModel.Customer dataModelCustomer, ViewModel.Customer customer)

{
if (customer == null)
{
throw new ArgumentNullException("customer");
}
if (dataModelCustomer == null)
{
throw new ArgumentNullException("dataModelCustomer");
}
dataModelCustomer.Email = customer.Email;
dataModelCustomer.FirstName = customer.FirstName;
dataModelCustomer.LastName = customer.LastName;
dataModelCustomer.MiddleName = customer.MiddleName;
dataModelCustomer.Phone = customer.Phone;
dataModelCustomer.PhoneExt = customer.PhoneExt;
dataModelCustomer.Url = customer.Url;
dataModelCustomer.Language = "en-us"; // only support en-Us in the UI at this time
dataModelCustomer. ["EMAILOPTIN"] = Convert.ToInt64(customer.EmailOptIn); ///NEW Code
5. Add the following example code to ConvertToDataModel immediately before the return statement:
dmCustomer["Age"] = customer.Age;
dmCustomer["SpecialOffers"] = customer.SpecialOffers;
To modify Customer.js
1. Open Customer.js in the Scripts\Scripts folder of Storefront.sln.
2. Add the following code to the function updateCustomer.
/// NEW Code

if ($view.find('.msax-EmailOptInCheckBox').is(':checked')) {
customer.EmailOptIn = true;
}
else {
customer.EmailOptIn = false;
}//NEW code
The following example shows the function after the code is added.
// Update a customer
this.UpdateCustomer = function () {
if (!Microsoft.Trigger($view, "UpdateCustomer")) {
return;
}
validator.Validate($view);
// NEW Code
if ($view.find('.msax-EmailOptInCheckBox').is(':checked')) {
customer.EmailOptIn = true;
}
else {
customer.EmailOptIn = false;
} //NEW code
if (validator.IsValid) {
services.UpdateCustomer(customer);
}
}
To modify CustomerDisplay.js
1. Open CustomerDisplay.js in the Scripts\Scripts folder of Storefront.sln.
2. Add the following code to the Initialize function.
// NEW Code
if (customer.EmailOptIn) {
$view.find('.msax-EmailOptInCheckBox').prop('checked', true);
}
else {
$view.find('.msax-EmailOptInCheckBox').prop('checked', false);
}
$view.find('.msax-EmailOptInCheckBox').attr("disabled", true);//NEW code
The following example shows the Initialize function after adding the code.
// CustomerViewModel constructor.
function Initialize() {
// Attach the Render event to the AfterRefresh
// event so when the data is loaded it will be
// displayed immediately.
services.OnGetCustomerSuccess(onGetCustomerSuccess);
services.OnGetCustomerFailure(onGetCustomerFailure);
binder = new Microsoft.Dynamics.Retail.SharePoint.Web.UI.TemplateBinder(
$view.find('.msax-CustomerDisplayTemplate'),
$view.find('.msax-CustomerDisplayContainer'));
// Set the customer control to refresh upon page load,
me.GetCustomer();
}
// bind the customer to the display only fields

this.BindCustomerDisplayData = function (customer) {
$view.find('.msax-CustomerDisplayAddress1').text(customer.FirstName + ' ' + customer.MiddleName + ' ' + customer.LastName);
$view.find('.msax-CustomerDisplayAddress2').text(customer.PrimaryAddress.StreetNumber + ' ' + customer.PrimaryAddress.Street);
$view.find('.msax-CustomerDisplayAddress3').text(customer.PrimaryAddress.City + ' ' + customer.PrimaryAddress.State + ' ' + customer.Pr
$view.find('.msax-CustomerDisplayAddress4').text(customer.PrimaryAddress.Country);
$view.find('.msax-CustomerDisplayPrimaryEmail').text(customer.Email);
$view.find('.msax-CustomerDisplayLoyaltyNumber').text(customer.LoyaltyCardNumber);
// NEW Code
if (customer.EmailOptIn) {
$view.find('.msax-EmailOptInCheckBox').prop('checked', true);
}
else {
$view.find('.msax-EmailOptInCheckBox').prop('checked', false);
}
$view.find('.msax-EmailOptInCheckBox').attr("disabled", true); //NEW code
}
Make changes to the controller

To modify SharePointWebControls/Customer/Customer.cs
1. Open Customer.cs in the SharePoint.Web.Controls/Customer folder.
2. Add the following code to the RetailWebControl class.
private HtmlInputCheckBox emailOptIn; // NEW code
The following example shows the after adding the code to the RetailWebControl class.
public class Customer : RetailWebControl

{
private HtmlInputText firstName;
private HtmlInputText lastName;
private HtmlInputText email;
private HtmlInputText phone;
private
private
private
private
private
private
HtmlInputText street;
HtmlInputText city;
HtmlInputText state;
HtmlInputText zipCode;
HtmlInputText country;
HtmlInputCheckBox emailOptIn; // NEW code
3. Add the following two code blocks to the GetCustomerTemplate method.

This code creates the checkbox.
///NEW code
this.emailOptIn = ControlFactory.CreateCheckBox("msax-EmailOptInCheckBox");
this.emailOptIn.AddAttribute(AXDataBindAttributes.Value, "EmailOptIn");
HtmlLabel emailOptInLabel = ControlFactory.CreateLabel(ControlResources.CustomerEmailOptIn, null, this.emailOptIn);
HtmlFieldPanel emailOptInContainer = ControlFactory.CreateFieldPanel(emailOptInLabel, this.emailOptIn, "msax-CustomerEmailOptI
This code adds the control to the container.
contactInfo.Controls.Add(emailOptInContainer);
4. The following example shows the GetCustomerTemplate method with the new code added.
private HtmlTemplate GetCustomerTemplate()

{
// Create the master template to put the shopping cart table in.
HtmlTemplate template = new HtmlTemplate();
template.AddCssClass("msax-CustomerTemplate");
this.CssClass = "msax-CustomerControl";
HtmlFieldSet contactInfo = ControlFactory.CreateFieldSet("msax-ContactInfoControls");

HtmlParagraph contactInfoParagraph = ControlFactory.CreateParagraph("msax-ContactInfoHeader");
contactInfoParagraph.InnerText = ControlResources.CustomerContactInformation;
// Create the controls

this.email = ControlFactory.CreateTextBox("msax-EmailTextBox");
this.email.AddAttribute(AXDataBindAttributes.Value, "Email");
this.email.AddRegularExpressionValidator(ControlResources.CustomerEmailNotSpecified, @"\w+([-+.]\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*"
this.email.MaxLength = 255;
HtmlLabel emailLabel = ControlFactory.CreateLabel(ControlResources.CustomerEmail, null, this.email);
HtmlFieldPanel emailContainer = ControlFactory.CreateFieldPanel(emailLabel, this.email, "msax-CustomerEmail");
this.firstName = ControlFactory.CreateTextBox("msax-FirstNameTextBox");
this.firstName.AddAttribute(AXDataBindAttributes.Value, "FirstName");
this.firstName.AddRequiredFieldValidator(ControlResources.CustomerFirstnameNotSpecified, "");
this.firstName.MaxLength = 100;
HtmlLabel firstNameLabel = ControlFactory.CreateLabel(ControlResources.CustomerFirstName, null, this.firstName);
HtmlFieldPanel firstNameContainer = ControlFactory.CreateFieldPanel(firstNameLabel, this.firstName, "msax-CustomerFirstName");
this.lastName = ControlFactory.CreateTextBox("msax-LastNameTextBox");
this.lastName.AddAttribute(AXDataBindAttributes.Value, "LastName");
this.lastName.AddRequiredFieldValidator(ControlResources.CustomerLastnameNotSpecified, "");
this.lastName.MaxLength = 100;
HtmlLabel lastNameLabel = ControlFactory.CreateLabel(ControlResources.CustomerLastName, null, this.lastName);
HtmlFieldPanel lastNameContainer = ControlFactory.CreateFieldPanel(lastNameLabel, this.lastName, "msax-CustomerLastName");
this.phone = ControlFactory.CreateTextBox("msax-PhoneTextBox");
this.phone.AddAttribute(AXDataBindAttributes.Value, "Phone");
this.phone.MaxLength = 255;
HtmlLabel phoneLabel = ControlFactory.CreateLabel(ControlResources.CustomerPhone, null, this.phone);
HtmlFieldPanel phoneContainer = ControlFactory.CreateFieldPanel(phoneLabel, this.phone, "msax-CustomerPhone");
/// NEW code
this.emailOptIn = ControlFactory.CreateCheckBox("msax-EmailOptInCheckBox");
this.emailOptIn.AddAttribute(AXDataBindAttributes.Value, "EmailOptIn");
HtmlLabel emailOptInLabel = ControlFactory.CreateLabel(ControlResources.CustomerEmailOptIn, null, this.emailOptIn);
HtmlFieldPanel emailOptInContainer = ControlFactory.CreateFieldPanel(emailOptInLabel, this.emailOptIn, "msax-CustomerEmailOptIn");
/// NEW code
// Add the individual controls to the fieldset
contactInfo.Controls.Add(contactInfoParagraph);
contactInfo.Controls.Add(emailContainer);
contactInfo.Controls.Add(firstNameContainer);
contactInfo.Controls.Add(lastNameContainer);
contactInfo.Controls.Add(phoneContainer);
contactInfo.Controls.Add(emailOptInContainer); //NEW code
HtmlFieldSet primaryAddressInfo = ControlFactory.CreateFieldSet("msax-AddressInfoControls");
HtmlParagraph primaryAddressInfoParagraph = ControlFactory.CreateParagraph("msax-AddressInfoHeader");
primaryAddressInfoParagraph.InnerText = ControlResources.CustomerAddressInformation;
To modify SharePointWebControls/Customer/CustomerDisplay.cs
1. Open CustomerDisplay.cs
2. Add the following code line to the header.
using System.Web.UI.HtmlControls; /// NEW Code
3. Add the following code to the GetCustomerTemplate method.
/// NEW code

HtmlLabel displayEmailOptInLabel = ControlFactory.CreateLabel(ControlResources.CustomerEmailOptIn, "msax-CustomerDisplayEmailOptInL
HtmlInputCheckBox displayEmailOptIn = ControlFactory.CreateCheckBox("msax-CustomerDisplayEmailOptIn");
/// NEW code
4. Add the following code to the GetCustomerTemplate method.
/// NEW Code

displayFieldSet.Controls.Add(displayEmailOptInLabel);
displayFieldSet.Controls.Add(displayEmailOptIn);
/// NEW Code
5. The following example shows the new code added to the GetCustomerTemplate method.
private HtmlTemplate GetCustomerTemplate()

{
// Create the master template to put the shopping cart table in.
HtmlTemplate template = new HtmlTemplate();
template.AddCssClass("msax-CustomerDisplayTemplate");
this.CssClass = "msax-CustomerDisplayControl";
HtmlFieldSet displayFieldSet = ControlFactory.CreateFieldSet("msax-CustomerDisplayControls");
HtmlLabel displayAddressLabel = ControlFactory.CreateLabel(ControlResources.CustomerDisplayAddressLabel, "msax-CustomerDisplayAddre

HtmlSpan displayAddressLine1 = ControlFactory.CreateSpan(string.Empty, "msax-CustomerDisplayAddress1");
HtmlLabel displayEmailLabel = ControlFactory.CreateLabel(ControlResources.CustomerDisplayPrimaryEmail, "msax-CustomerDisplayPrimary

HtmlSpan displayEmail = ControlFactory.CreateSpan(string.Empty, "msax-CustomerDisplayPrimaryEmail");
/// NEW code

HtmlLabel displayEmailOptInLabel = ControlFactory.CreateLabel(ControlResources.CustomerEmailOptIn, "msax-CustomerDisplayEmailOptInL
HtmlInputCheckBox displayEmailOptIn = ControlFactory.CreateCheckBox("msax-CustomerDisplayEmailOptIn");
/// NEW code
displayFieldSet.Controls.Add(displayAddressLabel);
displayFieldSet.Controls.Add(displayAddressLine1);
/// NEW Code
displayFieldSet.Controls.Add(displayEmailOptInLabel);
displayFieldSet.Controls.Add(displayEmailOptIn);
/// NEW Code
displayFieldSet.Controls.Add(displayEmailLabel);
displayFieldSet.Controls.Add(displayEmail);
template.Controls.Add(displayFieldSet);
return template;
}
}
Make the new fields visible on the site pages

Modify the following files in SharePoint.Web.Storefront/Controls project:
ControlResources.Designer.cs
ControlResources.resx
Add code to ControlResources.Designer.cs
/// <summary> NEW code
///
Looks up a localized string similar to Email for special offers:.
/// </summary>
internal static string CustomerEmailOptIn
{
get
{
return ResourceManager.GetString("CustomerEmailOptIn", resourceCulture);
}
}
/// NEW code
The following example shows where the new code is added in ControlResourcesDisigner.cs.
/// <summary>
///
Looks up a localized string similar to Share my information with Contoso partners..
/// </summary>
internal static string CustomerShareInformation {
get {
return ResourceManager.GetString("CustomerShareInformation", resourceCulture);
}
}
/// <summary> NEW code
///
Looks up a localized string similar to Email for special offers:.
/// </summary>
internal static string CustomerEmailOptIn
{
get
{
return ResourceManager.GetString("CustomerEmailOptIn", resourceCulture);
}
}
/// NEW code
/// <summary>
///
Looks up a localized string similar to State:.
/// </summary>
internal static string CustomerState {
get {
return ResourceManager.GetString("CustomerState", resourceCulture);
}
}
Add text to ControlResources.resx

Add text for the labels and messages to Storefront/Controls/ControlResources.resx as shown in the following table:
Name
Value
Comment
CustomerEmailOptIn
Email for special offers
Checkbox for EmailOptIn
2014 Microsoft
Walkthrough: Adding Properties to a Sales Order [AX 2012]

Updated: February 19, 2013
You can customize sales order properties to send additional data from your online store to Microsoft Dynamics AX to meet the needs of your business processes.
The starter store has sales order properties that you can use to capture data during order transactions. You can extend the sales order properties to send additional data
from your online store to Microsoft Dynamics AX during order transactions. For example, you could add an attribute called GiftWrap to indicate that an item should be
wrapped.
To customize sales order properties:
1. Create an attribute.
2. Add the attribute to an attribute group.
3. Assign the attribute group to your online store.
4. Set the attribute on a sales order.
Creating an Attribute
To create an attribute, you must define an attribute type and then assign the attribute type to your new attribute. In this example, you use an attribute type that is
included in Microsoft Dynamics AX. For more information about attributes, see Set up attributes and attribute types.
To create an attribute
1. In Microsoft Dynamics AX, click Product information management > Setup > Attributes > Attributes.
2. Click New. Enter the following values:
Property
Value
Name
GiftWrap
Friendly name
Gift wrap
Attribute type
StringDomain
Adding the Attribute to an Attribute Group

After you define your attribute, you can add it to an attribute group. For more information about attribute groups, see Set up retail attribute groups.
To create an attribute group and add your attribute

1. Click Product information management > Setup > Attributes > Attribute groups.
2. Click New. Enter the following values:
Property
Value
Name
SPSalesOrderGroup
Friendly name
Sales order attribute group
Description
Sales order attribute group
3. In Attributes, click Add.

4. Select GiftWrap, and then click Select.
5. Click OK.
Assigning the attribute group to your online store

After you create your attribute group, assign it to your online store. For more information, see Set up an online store.
To assign an attribute group to your online store
1. Click Retail > Common > Retail channels > Online stores. In the Online stores list, double-click your store.
2. Click the Set up tab and then click Sales order attributes.
3. In Channel attribute groups, click New.
4. In Name, select SPSalesOrderGroup.
Setting the attribute on a sales order

You can add the attribute to a sales order by adding business logic in the commerce runtime. Add the following code to add the attribute to the cart, save the cart, and
then create a sales order from the cart.
Var cart = orderManager.GetCart(cartId, accountNumber, false);

cart.AttributeValues.Add(new AttributeTextValue { Name = "GiftWrap", TextValue = "Yes" });
orderManager.SaveCart(cart);
orderManager.CreateOrderFromCart();
Next Steps
After you create a sales order on the commerce runtime, you can view the new attribute in Microsoft Dynamics AX.
To view the attribute in Microsoft Dynamics AX

1. In Microsoft Dynamics AX, click Retail > Periodic > Data distribution > Distribution schedule. Run the job P-0001_OC to run POS transactions in the online
channel.
2. Click Retail > Periodic > Synchronize online orders to create a sales order in Microsoft Dynamics AX.
3. Click Accounts receivable > Common > Sales orders > All sales orders. Click the Retail tab, and then click Retail attributes. You should see the attribute you
created.
2014 Microsoft
.NET Framework Classes for Microsoft Dynamics AX Retail online

sample store reference
Updated: March 27, 2014
This section contains reference documentation for the .NET Framework classes that are used in Microsoft Dynamics AX Retail online store development.
Tip
To apply advanced criteria to your search for Help about Microsoft Dynamics AX, use the WebSearchAx tool.
See also
Content roadmap for a Microsoft Dynamics AX Retail online store
2014 Microsoft

Dynamics AX Retail Online Store

Uploaded by

Copyright:

Available Formats

Dynamics AX Retail Online Store

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Dynamics AX Retail Online Store

Uploaded by

Copyright:

Available Formats

Table Of Contents

Install a Retail online store (e-commerce) [AX 2012]

Before you begin

Before you begin

Install URL Rewrite

Deploy and configure SharePoint

Verify that Microsoft Dynamics AX and

Verify that Microsoft Dynamics AX

Install Microsoft Dynamics AX 2012

You must install the following Retail features:

Prepare the developer environment

Set up the development environment for a Retail online store

Verify that SharePoint application

Verify that required SharePoint services

Verify role requirements

Create domain user accounts

Acquire Secure Sockets Layer (SSL)

Verify SQLCMD utility

Verify warehouse requirement

Verify SharePoint Managed Metadata connection properties

3. Verify that the following options are selected.

4. Save your changes.

Prepare your developer environment for signing updated source code

Option 1: Install the Retail online store by using Setup

Option 2: Deploy the Retail online store by using Windows PowerShell

Extract installation files

Configure settings in the Retail online store xml file

Before you begin

Configure settings in the oob-settings.xml file

1. Open the following directory:

Enter the name of the online store to

Microsoft Dynamics AX uses this value

Enter an ISO country code. This code

Enter the name of the country.

Enter a currency template. This template

Enter any alphanumeric value to uniquely

None, but we recommend a value of 1.

Enter a threshold value for the number

Enter the number of days to retain a

Enter a language code identifier (LCID).

This value is the name of a SharePoint

name of this value varies based on

The name of the logging service for this

Dynamics AX Retail Logging Service

The SharePoint diagnostics logging

General Logging [SharepointPackageInstanceIdentifier]

For events logged in the Windows NT

Dynamics AX Retail Monitoring [SharepointPackageInstanceIdentifier]

The port for the public online store

-------------------PORTS and URLS

50002 for the Fabrikam starter store

The port for the public online store

The port for the internal online store

The port for the internal product

Setting this parameter to true clears the

The local web address of the Retail

50004 for the Fabrikam starter store

50003 for the Fabrikam starter store

50001 for the Fabrikam starter store

address like www.contoso.com.) Enter a