Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two...

32
White paper Andreas Hofmann September 2015 Send feedback. www.microsoft.com/dynamics/ax Microsoft Dynamics AX 2012 R3 Cumulative Update 8 Retail extensibili ty (CRT, Retail Server, and MPOS) This document teaches you some of the basic steps to create a simple retail customization.

Transcript of Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two...

Page 1: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

White paperAndreas HofmannOctober 2015

Send feedback.www.microsoft.com/dynamics/ax

Microsoft Dynamics AX 2012 R3 Cumulative Update 8

Retail extensibility (CRT, Retail Server, and MPOS)This document teaches you some of the basic steps to create a simple retail customization.

Page 2: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 2

ContentsRetail extensibility (CRT, Retail Server, and MPOS) 3

Part 1: A simple customization 3

Overview 3High-level steps 5Detailed steps 6

Set up the Retail SDK CU8 for development 6Prepare MPOS to be run from Visual Studio from unchanged SDK code 6Activate the MPOS device 7Add a new operation and screen layout button to MPOS 10Customize the MPOS source code 12Add a new CRT service and register it with Retail Server 13Add a new Retail Server action and register it with Retail Server 15Test 16

Issues and solutions 17

Part 2: A new data entity 17

Overview 17High-level steps 19Detailed steps 19

Set up the Retail SDK CU8 for development 19Prepare MPOS to be run from Visual Studio from unchanged SDK code 20Activate the MPOS device 20Include the new entity in Microsoft Dynamics AX 20Configure CDX to sync the new entity 21Update and test the channel schema 23Add a CRT entity, service, request, response, and data accessor, and a Retail Server controller that has a new action 24Update the client framework to call the Retail Server endpoint 25Update the client framework channel manager with the new functionality 26Update the client framework’s view model 26Update the MPOS view to consume the updated view model 27

Issues and solutions 28

Page 3: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 3

Retail extensibility (CRT, Retail Server, and MPOS)This white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part 2 expands on the skills that you learn in the part 1 and discusses extensibility in Microsoft Dynamics AX 2012 R3 Cumulative Update 8 (CU8).

Part 1: A simple customizationOverviewPart 1 of this white paper will teach you the basic steps to perform a simple customization. Even for a simple customization, such as the one in the sample, there are quite a few “moving parts” that use different technologies. Therefore, this part includes some tricks that can help simplify the development mechanics, so that you can focus on the task at hand: extending the Retail solution.The download includes a zip file that contains all new and changed files for the sample.The steps are performed on the Contoso sample virtual machine (VM) image that you can request via Microsoft Dynamics Lifecycle Services (LCS, https://lcs.dynamics.com/Logon/Index), Most partners have access to the Contoso sample VM available from LCS. Alternatively, you can use PartnerSource (https://mbs.microsoft.com/partnersource/northamerica/) to download the VM. Make sure that you get the CU8 version.We recommended that you review some of the online resources about the Retail solution that are available at https://technet.microsoft.com/en-us/library/jj710398.aspx.This part of the white paper focuses on a very simple customization and covers the following basic steps:● Extend the Microsoft Dynamics AX commerce runtime (CRT) by writing a new CRT service. (No

change will be made to existing Retail software development kit [SDK] code.)● Extend Retail Server by writing a new customer action.● Make changes to the Retail Modern POS (MPOS) UI design in Microsoft Dynamics AX, and push the

changes to the store.● Extend MPOS by using the new Retail Server/CRT functionality from the UI.

Page 4: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 4

This sample customization updates the MPOS terminal to look up a cross-loyalty discount. It is useful for a company that allows customers to apply loyalty discounts from another external company. In this case, the discount must be looked up (by sending the phone number as an ID) and presented to the MPOS operator, who chooses to apply the discount to the current transaction. The following screen shots show the UI flow.

Page 5: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 5

All changes are made under the contoso\emmah account. If you use a different account, or different demo data, adjust the steps accordingly.

High-level steps1 Set up the Retail SDK CU8 for development.2 Prepare MPOS to be run from Microsoft Visual Studio from unchanged SDK code.3 Activate the MPOS device.4 Add a new operation and screen layout button to MPOS.5 Customize the MPOS source code.6 Add a new CRT service, and register it with Retail Server.7 Add a new Retail Server action, and register it with Retail Server.

Page 6: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 6

8 Test.During steps 4, 5, and 6, code changes must be made. Not all the code that must be written is included in this white paper. Therefore, to explain the code changes, the text refers to the files in the zip file.

Detailed stepsSet up the Retail SDK CU8 for developmentThe main point here is to keep a backup of the original Retail SDK CU8 folder, so that we can roll it back or diff against it later. In our case, the original SDK folder is under the Administrator user’s Documents folder.9 Open a Visual Studio x86 Native Tools Command Prompt windows as an administrator.10 Run the following commands:

a Mkdir "C:\Users\emmah\Documents\Retail SDK CU8"b Cd "C:\Users\emmah\Documents\Retail SDK CU8"c robocopy "C:\Users\Administrator\Documents\Retail SDK CU8" "C:\Users\emmah\Documents\

Retail SDK CU8" /EThe new folder is the working folder where you will make the changes. In a real development environment, we recommend that you use source control solutions, such as Microsoft Team Foundation Server or GIT.

Prepare MPOS to be run from Visual Studio from unchanged SDK code11 In Microsoft Visual Studio 2013, open the MPOS solution. The solution is located at C:\Users\

emmah\Documents\Retail SDK CU8\POS Clients\Windows\C1\Pos.sln.12 Change the target to Simulator.13 Press F5 to build the solution and run it in the debugger.

Note: If you receive a message that MPOS is already installed, see the Issues and solutions section at the end of this part of the white paper. After you have resolved the issue, the MPOS solution should open when you press F5 in Visual Studio.

Page 7: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 7

The Device activation dialog box should be displayed.

Activate the MPOS device14 Find out which channel database the Retail Server is configured to use. In inetmgr, browse to

RetailServer, select Explore, open the web.config file, and inspect the connection string. In this case, Retail Server is using RetailHoustonStore.

15 Look up the channel that is used (USRT > Retail >Setup > Retail Scheduler > Channel integration > Channel database).

Page 8: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 8

16 Look up the registers that are available (USRT > Retail > Common > Retail channels > Retail stores > Open Houston).

17 Look up whether devices already exist (USRT > Retail > Setup > Devices).We will reuse the HOUSTON-3 device that is in a Pending state. You can also create a new device.

18 Find the Retail Server URL for device activation by looking up the inetmgr configuration, finding the

port, and so on. For CU8, the Retail Server URL on our machine is http://ax2012r2a.contoso.com:35080/RetailServer/v1.

Page 9: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 9

19 Enter 000160 as the operator ID and 123 as the password.

20 Click Activate, and continue to the Sign in dialog box.

21 Perform a transaction to test the system.

Page 10: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 10

The device that we selected earlier now shows up as activated in Microsoft Dynamics AX.

Now that we have verified that everything works, we are ready to extend the code. Stop the debugger to quickly stop MPOS without having to sign out.

Add a new operation and screen layout button to MPOS22 In Microsoft Dynamics AX, add a new point of sale (POS) operation (USRT > Retail > Setup >

POS > Operations).

23 In the details for the HOUSTON store, find out what the screen layout is (USRT > Retail > Common > Retail channels > Retail stores > HOUSTON > Screen layout). In this case, the screen layout for the Modern POS for Windows application type is FABCSH16:9.Note: Screen layouts can also be assigned to a specific register or cashier. However, in this example, the whole store uses the same layout.

Page 11: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 11

24 Add a new button to Transaction screen 1 (USRT > Retail > Setup > POS > Screen layouts > FabMGR16:9 > Actions > Designer), and name it Cross Loyalty discount lookup.

25 Associate the button with the operation (in the designer, right-click the button, and then select Button properties).

26 Run job 1090 (USRT > Retail > Periodic > Data distribution > Distribution schedule > 1090 > Run now).

27 Verify that the job succeeded (USRT > Retail > Inquiries > CDX > Download sessions > Process status message).

Page 12: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 12

28 Press F5 to start MPOS, and sign in. You should see the new Cross Loyalty discount lookup button on the Transaction screen.

29 Click the button. You will see the message “Operation is not supported.” That makes sense, because MPOS has not been informed about the operation or how to handle it.

Customize the MPOS source code30 Unzip the Retail SDK CU8 - Extensibility Sample 1.zip file on top of your Retail SDK CU8 working

folder. This will update a few files for MPOS, and will also add the code for the CRT and Retail Server customization.The main code changes for MPOS are as follows:● In the Framework folder (generic for any client):

● Add a new activity to call out to Retail Server.● Add a new operation and operation handler for the whole UI flow (asking the user to enter the

loyalty card number, calling out to Retail Server, asking the user for confirmation, and applying a total discount).

● Register the new operation handler.● In the C1 folder (MPOS-specific):

● In CartView.ts, make sure that the discount is displayed/updated.● Implement activities.

31 In Visual Studio, clean the whole solution, and then press F5 to rebuild and test it.

Page 13: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 13

32 Click the Cross Loyalty discount lookup button again. This time, you will see that the new MPOS sample code is being used. A new dialog box appears, asking you to enter the loyalty card number.

If you type a phone number, and then click OK, you will receive an error. Why?The reason is that we have not yet customized Retail Server. Therefore, MPOS is making a call to an action that does not yet exist. By using a tool such as Fiddler, you can see that the POST request to http://ax2012r2a.contoso.com:35080/RetailServer/v1/Customers/GetCrossLoyaltyCardAction fails with a 404 (“Not Found”) error.

Add a new CRT service and register it with Retail ServerA CRT service is a small, single task as opposed to a workflow, which is composed of multiple tasks. To perform this simple task, we just have to write a function that takes the loyalty card number (phone number) and returns a discount. In a real-world system, that function would call another process or a web service, for example, to obtain that information. In the following sample code, the value will be hard-coded for a few phone numbers. (The source code is included in the zip folder, together with the full Visual Studio project.)We need to implement a request class, a response class, and the service, as shown here.

[DataContract]public sealed class GetCrossLoyaltyCardRequest : Request{ /// <summary> /// Gets or sets the loyalty card number /// </summary> [DataMember] public string LoyaltyCardNumber { get; set; }}public sealed class GetCrossLoyaltyCardResponse : Response{

Page 14: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 14

/// <summary> /// Gets or sets the calculated discount value. /// </summary> public decimal Discount { get; set; }}public class GetCrossLoyaltyCardService : IRequestHandler

The preceding code adds a simple new CRT service. Another customization approach is to edit existing functionality that is part of the Retail SDK. However, we recommend that you extend the CRT by adding new code instead of editing existing code. This approach will help make any upgrades to a future version of the SDK easier.To register a new CRT dynamic-link library (DLL) with the host (in this case, Retail Server), you must edit the commerceruntime.config file that is in the binary location of the host. Use inetmgr again to find the binary location of Retail Server, as you did earlier.

The Visual Studio projects for both the CRT and Retail Server extensions include two MSBuild files that make it easier to reference external files and deploy the target files. We highly recommend that you use a similar approach in your own development process (but not for production deployment).The first file, pre.settings, is included at the top of each project. It lets you adjust the Retail Server binary path.

Page 15: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 15

The second file, post.targets, is included at the bottom of each project. It must be included in any project that has to “deploy” the newly built binary to Retail Server’s binary folder.

Because the AfterBuild MSBuild target must be able to write to the Retail Server binary folder, Visual Studio has to be started with elevated privileges. In other words, you must run it as an adminstrator.

Add a new Retail Server action and register it with Retail Server[Export(typeof(IEdmModelFactory))][ComVisible(false)]public class ExtendedEdmModelFactory : CommerceModelFactory{ /// <summary> /// Builds entity sets. /// </summary> protected override void BuildActions() { base.BuildActions(); var var1 = CommerceModelFactory.BindEntitySetAction<Customer>("GetCrossLoyaltyCardAction"); var1.Parameter<string>("LoyaltyCardNumber"); var1.Returns<decimal>(); }}[ExtendedController("Customers")][CommerceAuthorization(AllowedRetailRoles = new string[] { CommerceRoles.Employee }, CheckRetailOperation = false)]public class NewEntitiesController : CustomersController{ [HttpPost] public decimal GetCrossLoyaltyCardAction(ODataActionParameters parameters) { CommerceRuntime runtime = CommerceRuntimeManager.Runtime; GetCrossLoyaltyCardResponse resp = runtime.Execute<GetCrossLoyaltyCardResponse>(new GetCrossLoyaltyCardRequest() { LoyaltyCardNumber = (string)parameters["LoyaltyCardNumber"] }, null); return resp.Discount; }}

The preceding code extends the CustomersController class by adding a new action that is named GetCrossLoyaltyAction. Therefore, the final URL that MPOS uses is http://ax2012r2a.contoso.com:35080/RetailServer/v1/Customers/GetCrossLoyaltyCardAction.For this example, it makes sense to extend the CustomersController class. However, in other cases, you might have to add your own custom controller class.

Page 16: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 16

To register a new Retail Server DLL, you must edit the Web.config file that is located in the root of the Retail Server web application path. Use inetmgr again to find the location.

Test33 Run through MPOS.34 Add a new item. 35 Click the new Cross Loyalty discount lookup button, and enter a phone number. MPOS should

return 0. 36 Enter 425-999-3333. This time, MPOS should return 3.In Fiddler, we can see the request and response, and their valid values.

Page 17: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 17

Issues and solutionsIf you cannot run MPOS from the Pos.sln file because it is already installed, uninstall the application first. This link might also be helpful: http://blogs.msdn.com/b/wsdevsol/archive/2013/01/28/registration-of-the-app-failed-another-user-has-already-installed-a-packaged-version-of-this-app-an-unpackaged-version-cannot-replace-this.aspx

Part 2: A new data entityOverviewPart 2 of this white paper expands on the knowledge that you gained in part 1. If you get stuck, we recommended that you review part 1. Some of that information is required and assumed.The steps in this section are performed on the AX 2012 R3 CU8 virtual machine image (Contoso sample VM) that you can request via Microsoft Dynamics Lifecycle Services (LCS, https://lcs.dynamics.com/Logon/Index), Most partners have access to the Contoso sample VM available from LCS. Alternatively, you can use PartnerSource (https://mbs.microsoft.com/partnersource/northamerica/) to download the VM. Make sure that you get the CU8 version.We recommended that you review some of the online resources about the Retail solution that are available at https://technet.microsoft.com/en-us/library/jj710398.aspx.The part of the white paper covers the following steps:● Microsoft Dynamics AX: Add a new data entity that is related to a retail store, and populate it by

using a job (no UI).● Commerce Data Exchange (CDX): Configure CDX to include the new table in data

synchronizations.● CRT: Add a new data entity and new service.● Retail Server: Expose a new controller for the new entity, and add a new OData action.● MPOS: Add plumbing to call Retail Server, and update the UI to expose data.The changed code is available in a zip file that includes only the files that have been added or changed. This zip file can be applied (after you back up your existing SDK) on top of the Retail SDK CU8 folder. Note that the zip file also includes the changes from part 1 of this white paper.

Page 18: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 18

This sample customization updates the MPOS terminal to show more detailed opening and closing times for a store. Remember that a store worker can look up item availability across multiple stores. Therefore, as part of that flow, the worker can tell a customer whether a particular store is currently open. The following screen shots show the UI flow.

Page 19: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 19

Notes:

● The sample illustrates the process for a simple customization. It is not intended for product use.● All changes are made under the contoso\emmah account. If you use a different account, or

different demo data, adjust the steps accordingly.

High-level steps37 Set up the Retail SDK CU8 for development.38 Prepare MPOS to be run from Visual Studio from unchanged SDK code.39 Activate the MPOS device.40 Include the new entity in Microsoft Dynamics AX.41 Configure CDX to sync the new entity.42 Update and test the channel schema.43 Add a CRT entity, service, request, response, and data accessor, and a Retail Server controller that

has a new action.44 Update the client framework to call the Retail Server endpoint.45 Update the client framework channel manager with the new functionality.

Page 20: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 20

46 Update the client framework’s view model.47 Update the MPOS view to consume the updated view model.48 Test.

Detailed stepsSet up the Retail SDK CU8 for developmentSee the corresponding section in part   1 of this white paper.

Prepare MPOS to be run from Visual Studio from unchanged SDK codeSee the corresponding section in part   1 of this white paper.

Activate the MPOS deviceSee the corresponding section in part   1 of this white paper.

Include the new entity in Microsoft Dynamics AXTo hold store hours, we will use a new table that is named ISVRetailStoreDayHoursTable. This table will hold each store’s opening and closing times for each day of the week.In the download file, you can find the XPO file at SampleInfo\Sample2_StoreDayHours.xpo. This file includes two items: the ISVRetailStoreDayHoursTable table, and a simple job, Temp_InsertData, that populates sample data for the Houston store.49 Import the XPO file into Microsoft Dynamics AX.50 Run the Temp_InsertData job at least once. 51 In Microsoft SQL Server Management Studio, inspect the table.

Page 21: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 21

Configure CDX to sync the new entity52 In Microsoft Dynamics AX, add a new location table and the appropriate columns to the AX 2012 R3

schema (USRT > Retail > Setup > Retail channel schema).

53 Create a new scheduler subjob (USRT > Retail > Setup > Scheduler subjobs).54 Click Transfer field list, and make sure that the fields match.

Page 22: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 22

55 Add the new subjob to the 1070 Channel configuration job (USRT > Retail > Setup > Scheduler job).

56 Edit the table distribution XML so that it includes the new table (USRT > Retail > Setup > Retail channel schema).

The easiest way to complete this step is to copy the XML in the Table distribution field, edit it in an XML editor, and then paste the edited XML back into the field. You must add the following XML fragment in two places. In both places, it has to be added inside the XML node for the RetailStoreTable table.

<Table name="ISVRETAILSTOREDAYHOURSTABLE"> <LinkGroup> <Link type="FieldMatch" fieldName="RetailStoreTable" parentFieldName="RecId" /> </LinkGroup></Table>

57 Click Generate classes (USRT > Retail > Setup > Retail channel schema > AX 2012 R3).

Page 23: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 23

Update and test the channel schemaYou must make an equivalent change to the table schema on the channel side. This has to be done to all channel databases. 1 In SQL Server Management Studio, create the table. You can find the file in the download file, at

SampleInfo\ChannelSchemaUpdates.txt.Because this is a sample, we will not add stored procedures. We just do that in code. However, we recommend that you use sprocs for performance and security reasons.

2 When you have finished, go back to Microsoft Dynamics AX, and run the 1070 job (USRT > Retail > Periodic > Distribution schedule > 1070 > Run now).

3 Verify that the job succeeded (USRT > Retail > Inquiries > Download sessions > Process status messages). You should see a status of Applied for the stores.

Page 24: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 24

Add a CRT entity, service, request, response, and data accessor, and a Retail Server controller that has a new actionUse the solution at SampleInfo\RSCRTExtension\RSCRTExtension.sln in the zip file to inspect the code.Because this step is based on the part 1 of the white paper, we assume that you have already completed the following tasks:● Configure the pre.settings file (for rapid deployment as part of the build into Retail Server’s bin

directory).● Configure Retail Server’s version of commerceRuntime.config to include the new CRT extension

DLL. ● Configure Retail Server’s web.config file to include the new extension DLL.The following code map view shows the code changes that are required.

You can see that we need a CRT request, response, service, data accessor, and entity. Additionally, Retail Server is customized to include a new StoreDayHoursController controller that exposes a new OData endpoint, GetStoreDaysByStore. That endpoint uses the CRT and the request object to get a response. It does not use the data service directly.If you have configured everything correctly, compiled the solution, and accessed the OData metadata URL for Retail Server (http://ax2012r2a.contoso.com:35080/RetailServer/v1/$metadata), you should see the new action.

Page 25: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 25

Update the client framework to call the Retail Server endpointThe first step is to make MPOS aware of the new entity and the new endpoint. This is basically proxy code that resembles the code that tools such as wsdl.exe would generate for .NET web services. The Retail team is investigating whether it will be able to provide a tool for automatic regeneration in a future release.

CommerceTypes.tsCommerceTypes.ts is a class that specifies the new entity as both an interface and a class.

export interface StoreDayHours { DayOfWeek: number; OpenTime: number; CloseTime: number; ExtensionProperties?: Entities.CommerceProperty[];}export class StoreDayHoursClass implements StoreDayHours { public DayOfWeek: number; public OpenTime: number; public CloseTime: number; public ExtensionProperties: Entities.CommerceProperty[]; /** * Construct an object from odata response. * * @param {any} odataObject The odata result object. */ constructor(odataObject?: any) { odataObject = odataObject || {}; this.DayOfWeek = odataObject.DayOfWeek ? odataObject.DayOfWeek : null; this.OpenTime = odataObject.OpenTime ? odataObject.OpenTime : null; this.CloseTime = odataObject.CloseTime ? odataObject.CloseTime : null; this.ExtensionProperties = undefined; if (odataObject.ExtensionProperties) { this.ExtensionProperties = []; for (var i = 0; i < odataObject.ExtensionProperties.length; i++) { this.ExtensionProperties[i] = odataObject.ExtensionProperties[i] ? new CommercePropertyClass(odataObject.ExtensionProperties[i]) : null; } } }}

CommerceContext.tsCommerceContext.ts is a class that exposes the OData data service to the rest of MPOS.

public storeDayHoursEntity(storeId?: string): StoreDayHoursDataServiceQuery { return new StoreDayHoursDataServiceQuery(this._dataServiceRequestFactory, "StoreDayHoursCollection", "StoreDayHours", Entities.StoreDayHoursClass, storeId);}export class StoreDayHoursDataServiceQuery extends DataServiceQuery<Entities.StoreDayHours> {

Page 26: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 26

constructor(dataServiceRequestFactory: IDataServiceRequestFactory, entitySet: string, entityType: string, returnType?: any, key?: any) { super(dataServiceRequestFactory, entitySet, entityType, returnType, key); } public getStoreDaysByStoreAction(storeId: string): IDataServiceRequest { var oDataActionParameters = new Commerce.Model.Managers.Context.ODataActionParameters(); oDataActionParameters.parameters = { StoreNumber: storeId}; return this.createDataServiceRequestForAction('GetStoreDaysByStore', Entities.StoreDayHoursClass, 'true', oDataActionParameters); }}

Update the client framework channel manager with the new functionalityNow that we have finished the low-level proxy code, we need to expose the new functionality in a more consumable way to the rest of the application framework. An appropriate location for the new functionality is IChannelManager, because it already encompasses similar functionality that is of more global, channel-related nature.

IChannelManager.ts:

getStoreDayHoursAsync(storeId: string): IAsyncResult<Entities.StoreDayHours[]>;

ChannelManager.ts:

public getStoreDayHoursAsync(storeId: string): IAsyncResult<Entities.StoreDayHours[]> { Commerce.Tracer.Information("ChannelManager.getStoreDayHoursAsync()"); var query = this._commerceContext.storeDayHoursEntity(); var action = query.getStoreDaysByStoreAction(storeId); return action.execute<Entities.StoreDayHours[]>(this._callerContext);}

Update the client framework’s view modelThe view model is an abstraction of the view that exposes public properties and commands for any view implementation to use. To customize the existing StoreDetailsViewModel model, we need to the following three elements:● A storeDayHours variable that holds the result for the view to bind to, and an

isStoreDayHoursVisible variable that the view can use to toggle visibility of the UI

public storeDayHours: ObservableArray<Model.Entities.StoreDayHours>;public isStoreDayHoursVisible: Computed<boolean>;

● Data initialization in the constructor

// empty arraythis.storeDayHours = ko.observableArray([]);

Page 27: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 27

this.isStoreDayHoursVisible = ko.computed(() => { return ArrayExtensions.hasElements(this.storeDayHours());});

● A data retrieval function that can be called by the view

public getStoreDayHours(): IVoidAsyncResult { var asyncResult = new VoidAsyncResult(this.callerContext); Commerce.Tracer.Information("StoreDetailsViewModel.getStoreDayHours()"); this.channelManager.getStoreDayHoursAsync(this._storeId) .done((foundStoreDayHours: Model.Entities.StoreDayHours[]) => { this.storeDayHours(foundStoreDayHours); Commerce.Tracer.Information("StoreDetailsViewModel.getStoreDayHours() Success"); asyncResult.resolve(); }) .fail((errors: Model.Entities.Error[]) => { asyncResult.reject(errors); }); return asyncResult;}

Update the MPOS view to consume the updated view modelStoreDetailsView.ts already calls into the view model to get store distance. For the sake of simplicity, we just hook into the done() event handler to call the new function.

this.storeDetailsViewModel.getStoreDistance().done(() => { this._storeDetailsVisible(true); this.indeterminateWaitVisible(false); this.storeDetailsViewModel.getStoreDayHours() .done(() => { this._storeDetailsVisible(true); this.indeterminateWaitVisible(false); }) .fail((errors: Model.Entities.Error[]) => { this.indeterminateWaitVisible(false); NotificationHandler.displayClientErrors(errors); });

Page 28: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Retail extensibility (CRT, Retail Server, and MPOS) 28

Finally, we update the HTML to expose the data.

Use the sample code in the download file, as was mentioned earlier. The code also includes a few changes that were not detailed here – for example, changes in resoures.resjson and Converters.ts.

Issues and solutionsIf you cannot run MPOS from the Pos.sln file because it is already installed, uninstall the application first. This link might also be helpful: http://blogs.msdn.com/b/wsdevsol/archive/2013/01/28/registration-of-the-app-failed-another-user-has-already-installed-a-packaged-version-of-this-app-an-unpackaged-version-cannot-replace-this.aspx

Page 29: Retail extensibility (CRT, Retail Server, and MPOS)€¦  · Web viewThis white paper contains two main parts. In part 1, you will learn how to perform a simple customization. Part

Send feedback.Microsoft Dynamics is a line of integrated, adaptable business management solutions that enables you and your people to make business decisions with greater confidence. Microsoft Dynamics works like and with familiar Microsoft software, automating and streamlining financial, customer relationship, and supply chain processes in a way that helps you drive business success.United States and Canada toll-free: (888) 477-7989Worldwide: (1) (701) 281-6500www.microsoft.com/dynamics

© 2015 Microsoft Corporation. All rights reserved.This document is provided “as-is.” Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. You bear the risk of using it.Some examples are for illustration only and are fictitious. No real association is intended or inferred.This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.