Handle Error Archive in an MDK App

0 %

Handle Error Archive in an MDK App

Details

Handle Error Archive in an MDK App

Jitendra Kansal

June 3, 2020

Created by

July 13, 2019

Intermediate

30 min.

Create an MDK app to display errors occurred while uploading local changes and implement some logic on how to handle such errors and then let users to fix it from the app by providing correct values.

You will learn

How to access Error Archive entity set to display local upload failure
How to handle a logic failure errors
How to fix these errors

Prerequisites

Tutorial group: Set Up for the Mobile Development Kit (MDK)
Download and install: SAP Mobile Services Client on your iOS or Android device
Download and install Barcode Scanner (required only for Android device)

You may clone an existing project from GitHub repository and start directly with step 7 in this tutorial.

You have built an MDK app with offline functionality. In offline store, you make a change to a local record and upload this change (from request queue) to backend but backend prevents this change to accept due to some business logic failure. This error is recorded in an Offline OData specific entity set named as ErrorArchive. This entity set has detailed information about the errors. It’s now up-to developers how they handle such errors and then let users to fix it from the app by providing the correct values.

ErrorArchive is exposed to the application as an OData entity set and is accessible through the OData API in the same way that the application accesses any other entity sets from the offline store.

In this tutorial, you need to carry out the following tasks in order to understand how to display and handle such errors:

Create a new project in SAP Web IDE using MDK CRUD Project template
Create two additional pages to display list of errors and their details
Create an action to navigate from error list page to its details page
Create a business logic to find the affected entity
Navigate to the affected record to handle the error

For this tutorial, you will use Mobile Services sample backend destination. You will modify a PurchaseOrderHeaders record by changing SupplierId field. Offline store saves this record in request queue database and when you sync it with backend, backend prevents updating this record due to business logic failure. This failure record will be listed in Error list page, from here, you can navigate to details page for more information. You will implement a logic to navigate from details page to the affected record.

Step 1: Create a new MDK project in SAP Web IDE

This step includes creating the Mobile Development Kit project in the Editor.

Launch the SAP Web IDE and select the MDK perspective by clicking on the icon in the left panel.
Right click Workspace folder and select New | MDK CRUD Project.

The MDK CRUD Project template creates the offline or online actions, rules, messages and list detail pages along with editable capability in respective pages. You can use such template to handle error archive situation.

More details on MDK template is available in help documentation.
Enter the Project Name as MDK_ErrorArchive and click Next.
Leave the default values in Application Creation step as it is, click Next.

In Service Creation step, provide and select the below information:

Field	Value
`Name`	`SampleServiceV2`
`Service URL`	`/destinations/mobileservices_cf`
`Application ID`	`com.sap.mdk.demo`
`Destination Name`	`com.sap.edm.sampleservice.v2`
`Enable Offline Store`	`Should be checked`

If you do not find mobileservices_cf destination, please ensure that you have followed this tutorial to setup this destination in SAP Cloud Platform cockpit.

If you see a Authentication Required pop-up, then enter your cloud platform User Name and password to authenticate.

For Offline OData capability only OData V2 is supported. OData V2 and V4 are supported for Online OData.

Regardless of whether you are creating an online or offline application, this step is needed app to connect to an OData service. When building an Mobile Development Kit application, it assumes the OData service created and the destination that points to this service is setup in Mobile Services and SAP Cloud Platform.

Since you will create an offline based app, hence Enable Offline Store option is selected.

Click Check Service to validate the service properties. If all the details are fine, you will see a success message. Click Next.

More details on Sample Back End is available in help documentation.
In Metadata Source step, select PurchaseOrderHeaders and PurchaseOrderItems‚ and click Next.
In following steps go with default selections and Finish the project creation.

After clicking Finish, the wizard will generate your MDK Application based on your selections. You should now see the MDK_ErrorArchive project in the project explorer.

Done

Log on to answer question

Step 2: Create a new page to display Error list

Generated project is offline enabled and includes two entity sets (PurchaseOrderHeaders and PurchaseOrderItems) on main page and these entities are fully CRUD enabled. You can create a new record and also modify an existing one.

Now, you will create a new page to display list of errors.
In SAP Web IDE project, right-click the Pages folder | New MDK Page | Section Page | Next.

You can find more details about section pages.
Enter the Page Name as ErrorList and click Next and then Finish on the confirmation step.
In the Properties pane, set the caption to Error List.
Next, add an Object Table control to display information like HTTP status code, HTTP method for the affected record.

In the Layout Editor, expand the Controls | Compound section, drag and drop the Object Table control onto the page area.

A Compound control contains a group of other controls. Unlike in a container control where you can add your own child controls (container items), the child controls in a compound control are fixed. You can populate each of its child control by defining its data binding, depending on which the child controls are created.
In the Properties pane, select the previously added service from the Service drop down and then select ErrorArchive entity set from the dropdown. This way, the Object Table has been bound to ErrorArchive entity.
Provide below properties:

Property Value

Service SampleServiceV2.service

Entity ErrorArchive

Property	Value
`Service`	`SampleServiceV2.service`
`Entity`	`ErrorArchive`

In Appearance section, provide below properties:

Property	Value
`Description`	leave it empty
`DetailImage`	leave it empty
`DetailImageIsCircular`	`false`
`Footnote`	leave it empty
`PreserveIconStackSpacing`	`false`
`ProgessIndicator`	leave it empty
`Status`	bind it to `{RequestMethod}`
`Subhead`	bind it to `{RequestURL}`
`SubStatus`	`leave it empty`
`Title`	bind it to `{HTTPStatusCode}`

You can find more details about ErrorArchive Entity Properties.

In Search section, update below properties:

Property Value

SearchEnabled true
In Behavior section, update below properties:

Property Value

AccessoryType disclosureIndicator
In EmptySection section, update below properties:

Property Value

Caption No Sync Errors Found

Property	Value
`SearchEnabled`	`true`

Property	Value
`AccessoryType`	`disclosureIndicator`

Property	Value
`Caption`	`No Sync Errors Found`

Done

Log on to answer question

Step 3: Create a new page to display Error details

View Full Instructions

Now, you will create another new page to display error details.
In SAP Web IDE project, right-click the Pages folder | New MDK Page | Section Page | Next.
Enter the Page Name as ErrorDetails and click Next and then Finish on the confirmation step.
In the Properties pane, set the caption to Error Details.

In this page, you would show which entity has been affected due to business logic failure and also want to display other information like detailed error message, request body, request URL etc.
Next, write a business logic to get the affected entity object and this object value will be shown in error details page.

Right click the Rules folder | New | File.

Enter the file name GetAffectedEntityHeaderCaption.js, click OK.

Copy and paste the following code.

export default function GetAffectedEntityHeaderCaption(context) {
 //Current binding's root is the errorArchiveEntity:
 //Get the affectedEntity object out of it
 let affectedEntityType = "Unknown EntitySet";
 let affectedEntity = context.getPageProxy().binding.AffectedEntity;
 let id = affectedEntity["@odata.id"];
 if (id.indexOf("(") > 0) {
   affectedEntityType = id.substring(0, id.indexOf("("));
 }
 return "Affected Entity: " + affectedEntityType;
}

@odata.id: an annotation that contains the entity-id. More details can be found here.

AffectedEntity: A navigation property that allows applications to navigate from an ErrorArchive entity to an entity in the offline store that is affected by the error.

Save your changes to the GetAffectedEntityHeaderCaption.js file.
Next, add an Object Table control in ErrorDetails.page to display some information like affected entity and id for affected record.

Open ErrorDetails.page, in the Layout Editor, expand the Controls | Compound section, drag and drop the Object Table control onto the page area.
In the Properties | Target pane, choose String Target from the dropdown and provide #Property:AffectedEntity value.

In Appearance section, provide below properties:

Property	Value
`Description`	leave it empty
`DetailImage`	leave it empty
`DetailImageIsCircular`	`false`
`Footnote`	leave it empty
`PreserveIconStackSpacing`	`false`
`ProgessIndicator`	leave it empty
`Status`	leave it empty
`Subhead`	`{@odata.id}`
`SubStatus`	leave it empty
`Title`	`Edit Affected Entity`

In Behavior section, update below properties:

Property Value

AccessoryType disclosureIndicator
Next, add a Header section bar to display affected entity information.

In the Layout Editor, expand the Controls | Section Bar section, drag and drop the Header control onto the Object Table control.

Now, bind its Caption property to GetAffectedEntityHeaderCaption.js file.
Next, you can also display additional information like detailed error message, request body, request URL etc.

In the Layout Editor, expand the Controls | Container section, drag and drop the Static Key Value control on the page area.

Update NumberOfColumns value to 1.

You can limit the number of columns to be displayed.
Next, you will add items to the container.

In the Layout Editor, expand the Controls | Container Item section, drag and drop the Key Value Item control in the Static Key Value control.

Provide the below information:

Property Value

KeyName HTTP Status Code

Value {HTTPStatusCode}

Drag and drop 4 more Key Value Item control in the Static Key Value control and provide the below information:

Property Value

KeyName Request Method

Value {RequestMethod}

Property Value

KeyName Request URL

Value {RequestURL}

Property Value

KeyName Request Body

Value {RequestBody}

Property Value

KeyName Error Message

Value {Message}

You should have final binding for all key value items as below:
Save your changes to the Error Details page.

Property	Value
`AccessoryType`	`disclosureIndicator`

Property	Value
`KeyName`	`HTTP Status Code`
`Value`	`{HTTPStatusCode}`

Property	Value
`KeyName`	`Request Method`
`Value`	`{RequestMethod}`

Property	Value
`KeyName`	`Request URL`
`Value`	`{RequestURL}`

Property	Value
`KeyName`	`Request Body`
`Value`	`{RequestBody}`

Property	Value
`KeyName`	`Error Message`
`Value`	`{Message}`

Done

Log on to answer question

Step 4: Navigate from Error list page to Error details page

When you click any record in Error List page, you want to navigate to Error Details page to view more information about this error.

Create a Navigation Action.

Right click the Actions folder | New MDK Action | Navigation Action | Next.

Provide the below information:

Field Value

Action Name ShowErrorDetails

Page to Open select ErrorDetails.page
Bind this action to onPress of Object Table in Error List page.

Open Error List page | Events tab, click the link icon for the OnPress property to open the object browser.

Double click the ShowErrorDetails.action action and click OK to set it as the OnPress Action.
Save your changes to the ErrorList.page file.

Field	Value
`Action Name`	`ShowErrorDetails`
`Page to Open`	`select ErrorDetails.page`

Done

Log on to answer question

Step 5: Navigate from Error details page to affected record

View Full Instructions

When you click an affected entity in Error details page, you want to bring the affected record so that you can fix business failure by modifying previous changes right there.

You can write a logic in JavaScript to handle the affectedEntity and then decide which action to call depends on which @odata.id is the affectedEntity and if there is no handler for an affected entity, app will display a toast message.

Create a Message Action to display this toast message.

Right click the Actions folder | New MDK Action | Message Action | Next.

Provide the below information:

Property	Value
`Action Name`	`UnknownAffectedEntityMessage`
`Type`	select `ToastMessage`
`Message`	`Affected Entity {{#Property:AffectedEntity/#Property:@odata.id}} doesn't have handler yet.`
`Duration`	4
`Animated`	`true`

Click Next and then Finish on the confirmation step.

Write a business logic to decide which action to call depends on which @odata.type is the affectedEntity and if there is no handler for an affected entity, app will display a toast message saying this affected entity doesn’t have a handle yet.
Right click the Rules folder | New | File.

Enter the file name DecideWhichEditPage.js, click OK.

Copy and paste the following code.

export default function DecideWhichEditPage(context) {
  //Current binding's root is the errorArchiveEntity:
  let errorArchiveEntity = context.binding;
  //Get the affectedEntity object out of it
  let affectedEntity = errorArchiveEntity.AffectedEntity;
  console.log("Affected Entity Is:");
  console.log(affectedEntity);

  let targetAction = null;
  let id = affectedEntity["@odata.id"]; //e.g. PurchaseOrderHeaders(12345)
  let affectedEntityType = "Unknown Entity Set"; //By default it's unknown type
  if (id.indexOf("(") > 0) {
    //Extracting the entity set type from @odata.id e.g. PurchaseOrderHeaders
    var patt = /\/?(.+)\(/i;
   var result = id.match(patt);
   affectedEntityType = result[1];
  }
  console.log("Affected Entity Type Is:");
  console.log(affectedEntityType);
  //Here we decide which action to call depends on which affectedEntityType is the affectedEntity
  // You can add more complex decision logic if needed
  switch (affectedEntityType) {
    case "PurchaseOrderHeaders":
        targetAction = "/MDK_ErrorArchive/Actions/PurchaseOrderHeaders/NavToPurchaseOrderHeaders_Edit.action";
      break;
    default:
        //Save the affected Entity's type in client data so that it can be displayed by the toast
        context.getPageProxy().getClientData().AffectedEntityType = affectedEntityType;
        // Show a toast for affectedEntityType that we do not handle yet
        return context.executeAction("/MDK_ErrorArchive/Actions/UnknownAffectedEntityMessage.action");
  }

  if (targetAction) {
    let pageProxy = context.getPageProxy();
    //Set the affectedEntity object to root the binding context.
    pageProxy.setActionBinding(affectedEntity);
    //Note: doing 'return' here is important to chain the current context to the action.
    // Without the return the ActionBinding will not be passed to the action because it will consider
    // you are executing this action independent of the current context.
    return context.executeAction(targetAction);
  }
}

Save your changes to the DecideWhichEditPage.js file.
Bind this file to onPress of Object Table in Error Details page.

Open Error Details page | Select Object Table control | Events tab, click the link icon for the OnPress property to open the object browser.

Double click the DecideWhichEditPage.js action and click OK to set it as the OnPress Action.
Save the changes to the ErrorDetails page.

Done

Log on to answer question

Step 6: Add a button on main page to view Error list

Now, that the Error List page is created, you will add a button on the Main page that navigates to Error List page.

Create a Navigation Action.

Right click the Actions folder | New MDK Action | Navigation Action | Next.

Provide the below information:

Field Value

Action Name ShowErrorList

Page to Open select ErrorList.page
On Main page, drag and drop the Section Button Container Item control onto the Page.

Provide Title as Error Archive.
Bind ShowErrorList.action to the onPress of Error Archive section button in Main page.

Go to Events tab, click the link icon for the OnPress property to open the object browser.

Double click the ShowErrorList.action action and click OK to set it as the OnPress Action.
Save the changes to the Main page.

Field	Value
`Action Name`	`ShowErrorList`
`Page to Open`	`select ErrorList.page`

Done

Log on to answer question

Step 7: Deploy and activate the application

So far, you have learnt how to build an MDK application in the SAP Web IDE editor. Now, we deploy this application definition to Mobile Services.

Right-click the MDK_ErrorArchive MDK Application in the project explorer pane and select MDK Deploy and Activate.
Let the default configuration as it is and click Next.

Filter Files will be filtered and ignored in web packing process.

Externals are the list of NPM modules that are part of the MDK Client application and should not be validated in the bundle.
Confirm the destination name and application id match where you want to deploy and click Next.

By default, automatically deploy option is selected, In other words, the application is automatically deployed from Mobile Services to your MDK client.
Click Next to finish the deployment from SAP Web IDE.

You should see Application deployed successfully message in console log.

Done

Log on to answer question

Step 8: Populate the QR code for app onboarding

SAP Web IDE has a feature to generate QR code for app onboarding.

Right click the MDK_ErrorArchive MDK Application in the project explorer pane and select MDK Show QR Code.

MDK Show QR Code option is greyed out if MDK project is not yet deployed and activated as per step 3.

Done

Log on to answer question

Step 9: Run the app in MDK client

Make sure you are choosing the right device platform tab above. Once you have scanned and onboarded using the onboarding URL, it will be remembered. When you Log out and onboard again, same onboarding URL settings will be reused without the need to scan. You will need to use 3rd party QR scanner app in Android or device Camera in iOS, if you would like to scan a different onboarding URL.

Launch Mobile Svcs app on your Android device. Tap GET STARTED to connect MDK client to SAP Cloud Platform.
Tap QR CODE SCAN to start the device camera for scanning the onboarding QR code.
Once scan is succeeded, tap CONTINUE.
Enter Email address and password to login to SAP Cloud Platform and tap Log On to authenticate.
Tap AGREE on End User License Agreement.
Choose a passcode with at least 8 characters for unlocking the app and tap NEXT.
Confirm the passcode and tap DONE.

Optionally, you can enable fingerprint to get faster access to the app data.
Tap OK.

The MDK client receives deployed metadata definitions as a bundle.

Now, you will see Main page with some entity sets being displayed and Offline store is being initialized.
You will modify a PURCHASEORDERHEADERS record, save it locally, sync it to the backend and if backend doesn’t accept this change due to some business logic failure, this record will appear in Error Archive list.

Navigate to PURCHASEORDERHEADERS list, tap either one of the record.

Tap edit icon.

Make some changes to SUPPLIERID value and SAVE it.

You will see Entity Updated toast message. You can always see this updated record reflecting in PURCHASEORDERHEADERS list which means offline store has accepted this change.
Navigate to Main.page, click SYNC to upload local changes from device to the backend and to download the latest changes from backend to the device.
Once you see Sync success message, navigate to ERROR ARCHIVE list.

There you will find affected entity which couldn’t get accepted by backend due to some business logic failure.
Tapping any record navigates to Error Details page with more information about error.

Here in ERROR MESSAGE you will see violates foreign key constraint and in REQUEST BODY, it shows the property that caused this failure.

It’s now up-to developers how to handle such errors and let users to modify record with correct values.

In this tutorial, we have added a business logic to find out which is affected entity and how to navigate to respective record to let users to modify this record with correct values. Once done, user can again SYNC it with backend.
Tap Edit Affected Entity and modify record with correct values.

Once you have scanned and onboarded using the onboarding URL, it will be remembered. When you Log out and onboard again, same onboarding URL settings will be reused without the need to scan. You will need to use 3rd party QR scanner app in Android or device Camera in iOS, if you would like to scan a different onboarding URL.

Launch Mobile Svcs app on your iOS device. Tap Scan to start the device camera for scanning the onboarding QR code.
Once scan is succeeded, tap Continue.
Enter Email address and password to login to SAP Cloud Platform and tap Log On to authenticate.
Tap Agree on End User License Agreement.
Choose a passcode with at least 8 characters for unlocking the app and tap Next.
Confirm the passcode and tap Done.

Optionally, you can enable Touch ID to get faster access to the app data, tap Enable.
Tap OK.

Now, you will see Main page with some entity sets being displayed and Offline store is being initialized.
You will modify a PurchaseOrderHeaders record, save it locally, sync it to the backend and if backend doesn’t accept this change due to some business logic failure, this record will appear in Error Archive list.

Navigate to PurchaseOrderHeaders list, tap either one of the record.

Tap Edit.

Make some changes to SupplierId value and Save it.

You will see Entity Updated toast message. You can always see this updated record reflecting in PurchaseOrderHeaders list which means offline store has accepted this change.
Navigate to Main.page, click Sync to upload local changes from device to the backend and to download the latest changes from backend to the device.
Once you see Sync success message, navigate to Error Archive list.

There you will find affected entity which couldn’t get accepted by backend due to some business logic failure.

Tapping any record navigates to Error Details page with more information about error.

Here in Error Message you will see SQL Exception: Foreign key constraint violation occurred and in Request Body, it shows the property that caused this failure.

It’s now up-to developers how to handle such errors and let users to modify record with correct values.

In this tutorial, we have added a business logic to find out which is affected entity and how to navigate to respective record to let users to modify this record with correct values. Once done, user can again Sync it with backend.
Tap Edit Affected Entity and modify record with correct values.

Once you have scanned and onboarded using the onboarding URL, it will be remembered. When you Log out and onboard again, same onboarding URL settings will be reused without the need to scan. You will need to use 3rd party QR scanner app in Android or device Camera in iOS, if you would like to scan a different onboarding URL.