Postfill Responses using Custom API

1. Prerequisites

1.1 You will need:

• Windows 10 laptop or MacBook. Current document follows Windows 10.
• Visual Studio 2019 Community Edition - Free ( download )
• Experience Management account with a running survey set-up
• Postman app ( download )

1.2 Setting it up:

• Install Visual Studio, Postman ( Takes: 30-60 minutes )
• Create a fresh clean development directory ( C:\Dev )

1.3 Understanding about WXM APIs:

The whole postman collection of WXM APIs can be imported from this link Primarily we would be using these two APIs mentioned below.

• Login Token API
• Update Answers API

1.4 Set-up to host Web API:

• Dev set-up can be done locally
• For UAT and Production set-up, it would require a server with basic configuration(or even shared server) which can host a web API. Here is list of items required to host a web API.
  1. Windows/Linux Server (This reference implementation is developed using ASP.Net Core which is compatible to run on Windows or Linux server)
  2. A domain resolving to the above server
  3. Valid SSL certificate

2. Example implementation scenarios

2.1.1 Airlines Usecase: Understand customer’s feedback pattern based on Departure and Arrival time

Let us take an example of an Airline company that is measuring experience across the journey of its customers. The brand is sending all the contextual data available at its disposal including passenger details (Name, age, location etc), Flight details (Flight name, Boarding city, Destination city, Scheduled Departure and Arrival time, Actual Departure and Arrival time etc) and other such information. From the Scheduled and Actual departure time, you could derive the delay and bucket them as On time/Less than 15 mins delay and More than 15 mins delay. The Departure and Arrival time can also be bucketed in 6 hour slot. The Airline will now be able to understand the NPS across these departure time segments and take action where required.

2.1.2 E-commerce Usecase: Understand customers spending amount based on customer’s age

In another example, we could look at an E-Commerce brand who also is sending a lot of contextual data including demographic, transactional and finance data. Here again we receive Age as an absolute value. By converting absolute age into Age groups of 18 and below, 19-30, 30-50, 50 and above, the brand was able to derive various insights across these age segments including NPS trends, products most liked, common concerns etc.

3. Workflow

4. Configuration and Development

4.1 Understanding the Experience Management Response format

Before updating the Experience Management response, its necessary to understand the response JSON format. This would help to formulate the required logic using the existing prefill values. Please refer this section for more details.

4.2 Understanding the Postfill API Structure and customizing for your own usecase

• Inside C:\Dev, download the Experience Management reference solution from here

• Go inside “WXMPostfillAPI” folder

• Launch the Visual Studio solution file (WXMPostfillAPI.sln)

• This file structure for this solution is shown below. It basically contains Controllers file and configuration file (appsettings.json). Further logic can be coded in separate class and file, however the API process initiation would always start from Controllers.

  
  

• You can see two controllers here:

  a) AirlinePostFillController.cs - for the airlines use cases to post fill for arrival and departure bucket and to identify if the flight started late from origin

  b) AgeGroupPostFillController.cs - for the age group categorization use case

• Code structure is same for both the controllers and only the information being prefilled is different here. As per the Route used in the code, API end-point would be

  {Base URL} + /api/Postfill/airlines

  Any request arriving on the above end-point with “NotificationBody” object as the input will be processed by “Postfill” method

  
  

• Follow into methods(F12) to see the implementation. In this method, copy the answer object where more data would be postfilled.

  
  

• In the following method, based on the “DepartureDateTime” value, another prefill called “DepartureBucket” will be set and added in the answer object. For any different usecase, this logic should be alligned accordingly.

  
  

• Finally, the answer object is submitted to WXM using “Update Answers” API. Now the response contains postfilled information also along with customer responded answers and already set prefills.

  
  

• In same “Postfill” method, Postfills are also happening for “ArrivalBucket” and “Delay_15” fields which is also similar flow as described above.

• In “AgeGroupPostFillController.cs” file, you can refer how to categorize absolute “Age” figures as “Age Group”. The code flow is same as described above.

  
  

• All the configurations would reside in appsettings.json. For this reference solution, following are the configuration parameters used.

  
  

5. Testing

5.1 Dev Testing

Its essential to run some dev tests before pushing the code to UAT or production to make sure all developed code is bug free and working as expected. Here are some steps which might make it easier to test this Postfill API.

• Once your code is built(Ctrl+Shift+B) successfully, click on “IIS Express” to run in locally on your machine.

  
  

• You should see this message in your default browser.

  
  

• Above screenshot also tell us the Base URL of this locally running API

  BASE URL: https://localhost:44353

  Local API end-point for Airlines usecase: https://localhost:44353/api/Postfill/airlines

  Local API end-point for Age Group usecase: https://localhost:44353/api/Postfill/AgeGroup

• Get the Notification response JSON structure using this step

• Load it up in Postman and submit the request.

  
  

• Postfilled values should be available in responses and can be verified using the Experience Management Dashboard. In the below example, we can verify that these three prefills from reference example are populating properly.

  
  

5.2 UAT/Prod Testing

• For UAT/Prod deployments, both Windows or Linux server can be used. Here are the deployment guide from Microsoft for Windows and Linux.

• Once the deployed API end-point is ready, create/update a notification in Experience Management as per this section