Install a Retail online store (e-commerce)
Important
This content is archived and is not being updated. For the latest documentation, see Microsoft Dynamics 365 product documentation. For the latest release plans, see Dynamics 365 and Microsoft Power Platform release plans.
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 |
Details |
|---|---|
Verify that your computing environment meets all system requirements |
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 |
|
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 |
You must install the following Retail features:
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. .gif "Important") 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:
|
Verify role requirements |
|
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.
|
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. |
.gif "JJ991927.collapse_all(en-us,AX.60).gif")
Verify SharePoint Managed Metadata connection properties
You must verify that the SharePoint Managed Metadata connection required options are enabled.
In SharePoint Central Administration, under Application Management, click Manage service applications.
Highlight the Managed Metadata Service Connection row and then click Properties.
.gif "SharePoint Managed Metadata application")
Verify that the following options are selected.
.gif "SharePoint Managed Metadata properties")
Save your changes.
If you are installing Microsoft Dynamics AX 2012 R3 Cumulative Update 8, you must also complete the following steps:
In Central Administration, under Application Management, click Manage Service Applications.
Click Managed Metadata Service.
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.
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:
Save the file in the Retail SDK folder and give it a name Name.snk.
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).
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.
Start Microsoft Dynamics AX Setup. Under Install, select Microsoft Dynamics AX components.
Advance through the first wizard pages.
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.
On the Select installation type page, click Custom installation, and then click Next.
On the Select components page, select Retail online channel, and then click Next.
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.
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 you’re 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.
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.
On the Ready to install page, click Install.
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.
Start Microsoft Dynamics AX Setup. Under Install, select Microsoft Dynamics AX components.
Advance through the first wizard pages.
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.
On the Select installation type page, click Custom installation, and then click Next.
On the Select components page, select Retail online channel, and then click Next.
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.
On the Configure a Microsoft Dynamics AX Retail online store page, clear the Configure Retail online store option. Click Next.
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.
On the Ready to install page, click Install.
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.
Open the manifest.xml file in the following directory on the SharePoint server:
C:\...\Retail Online Channel\StoreFront\SP
Delete the following line of code from the manifest.xml file:
<Assembly Location="Microsoft.Web.Administration.dll" DeploymentTarget="GlobalAssemblyCache" />
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.
Open the following directory:
C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Online Channel\tools
Open the oob-settings.xml file in Microsoft Visual Studio or a text editor, such as Notepad.
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/region. 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 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.
.gif "Note")
Note
The value of this property and the value of the previous property (StoreFront_DeviceChannelsListName) work together. For example, an en-US online store uses the 1033, Device Channels values and an fr-FR online store uses the 1036, Canaux des appareils values.Device Channels
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 ([SharepointPackageInstanceIdentifier]) unless you are a developer and understand the repercussions of making 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 ([SharepointPackageInstanceIdentifier]) unless you are a developer and understand the repercussions of making a change.
Dynamics AX Retail Monitoring [SharepointPackageInstanceIdentifier]
--------------------
PORTS and URLS
--------------------
StoreFrontUrlPort_Public
The port for the public online store site: You can specify any available port.
40002
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
50004 for the Fabrikam starter store
StoreFrontUrlPort_Internal
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
50003 for the Fabrikam starter store
ProductCatalogUrlPort_Internal
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
50001 for the Fabrikam starter store
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 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.
http://%COMPUTERNAME%:[StoreFrontUrlPort_Public]
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 repercussions of making a change.
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]
--------------------
SSL
--------------------
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 repercussions of making a change.
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.
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.None
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.
Important
This path cannot contain any special characters. If the path contains a special character deployment fails.None
StoreFrontPublicSSLCertPfxFileName
Enter the file name and extension. By default the extension is .pfx.
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.
None
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
--------------------
DOMAIN ACCOUNTS and MISCELLANEOUS
--------------------
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]) unless you are a developer and understand the repercussions of making 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 value="Domain\User".
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
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 value="Domain\User".
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 empty if the database is not part of a named instance.
None
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.
Logon to the Facebook developer site
Register as a developer on the Facebook developer site.
Click Create New App and then follow the prompts to create a new application.
In the Select how your application integrates with Facebook section, click the Website with Facebook Login option and specify the Site URL.
Click Save Changes.
On the applications landing page, select the application that you just created.
In the oob-settings.xml file, search for FacebookApplicationId. Replace the value with the Facebook ID. Retain the quotation marks.
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.
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.
Search in the oob-settings.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.
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.
Open the following folder:
C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Online Channel\tools
Open the Install-Prerequistes.ps1 file in Microsoft Visual Studio.
Search for line 155:
RoboCopy $trustedIdentityTokenIssuerConfig.CertificateDirectory $certificateLocalCopyDirectory $trustedIdentityTokenIssuerConfig.SigningCertificateCerFileName $trustedIdentityTokenIssuerConfig.SigningCertificatePfxFileName
Replace that line with the following:
RoboCopy $trustedIdentityTokenIssuerConfig.CertificateDirectory $certificateLocalCopyDirectory $trustedIdentityTokenIssuerConfig.SigningCertificateCerFileName $trustedIdentityTokenIssuerConfig.SigningCertificatePfxFileName $trustedIdentityTokenIssuerConfig.SslCertificateAuthorityCerFileName
Save your changes.
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.
Open the oob-topology.xml file in Microsoft Visual Studio or a text editor, such as Notepad.
Search in the oob-topology.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">
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 oob-topology.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 oob-topology 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-topology.xml file to preserve databases, web applications, features, and settings, as described earlier in this topic. |
|
SharePoint Server actions performed by this script |
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.
|
Other actions performed by the script The script performs the following pre-deployment checks, by default. You can customize which checks are performed. |
|
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.
Warning
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.
-
Open the following folder:
C:\Program Files (x86)\Microsoft Dynamics AX\60\Retail Online Channel\tools
-
Open the Custom-Scripts.ps1 file in Microsoft Visual Studio or a text editor, such as Notepad.
-
Search for and delete the following line of code:
(if((Test-Connection $value -Count 1 -Quiet) -ne $True))
-
Save your changes.
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 you’ve written and scripts that have been signed by a trusted publisher.
On the server where you want to run the script, open the tools folder where the PowerShell scripts are installed.
If you’re 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 you’re 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 “<Path to directory>”.
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.
Deactivates features
Uninstalls solution packages
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.
In SharePoint Central Administration under System Settings, click Manage services on server.
Verify that the Retail Publishing Connector Service 1 is running.
In SharePoint Central Administration, click Monitoring, and then click Check job status.
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.
In SharePoint Central Administration, click Application Management, and then click View all site collections.
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.
In SharePoint Central Administration, click the Web application drop-down list and then click Change web application.
Click the Out of box Store front – Public web application.
In the URL section, verify that you see the following URLs:
http://ServerName:40002/sites/RetailPublishingPortal
http://ServerName:40002
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.
Paste the public URL into a browser and press Enter. For example: http://ServerName:40002/sites/RetailPublishingPortal
Click Register a new account.
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.
Browse the public portal site again (http:// ServerName:40002/sites/RetailPublishingPortal).
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 |
|
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.
Warning
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 -SettingsXmlFilePath oob-settings-updated.xml
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 -SettingsXmlFilePath oob-settings-updatedFabrikam.xml
Note
If you have multiple online channels, you must 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.
In SharePoint Central Administration, under System Settings, click Manage Farm Features.
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 you uninstall the parent solutions.
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 complete these steps, an IIS reset will occur, and Central Administration might become unavailable. If so, wait and try again.
After all the solutions have been retracted, remove the solution for each entry.
In Central Administration, under Manage Web Applications, delete all of the web applications by clicking Delete, and then clicking Delete Web Application.
Click Yes when you are prompted to delete content databases and to delete IIS websites. This step can take some time to complete.