Skip to Content

Handle Error Archive in an MDK App

test
0 %
Handle Error Archive in an MDK App
Details
// Explore More Tutorials

Handle Error Archive in an MDK App

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


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.

MDK

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.

MDK

This tutorial has been executed with Mobile Services in SAP Cloud Platform Neo and Cloud Foundry environment, please switch to either tab according to your environment.

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 on Workspace folder and select New | MDK CRUD Project.

MDK

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.

MDK

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
Application ID com.sap.mdk.demo
Destination Name com.sap.edm.sampleservice.v2
Enable Offline Store Should be checked

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

MDK

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.

MDK

Make sure that you have already created a new destination mobileservices_cf as per previous tutorial. This is required to connect SAP Web IDE to Mobile Services running in Cloud Foundry environment.

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 on Workspace folder and select New | MDK CRUD Project.

MDK

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.

MDK

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
Service URL com.sap.edm.sampleservice.v2
Enable Offline Store Should be checked

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

MDK

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.

MDK

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.

MDK
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.

MDK

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.

MDK

You can find more details about section pages.

Enter the Page Name as ErrorList and click Next and then Finish on the confirmation step.

MDK

In the Properties pane, set the caption to Error List.

MDK

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.

MDK

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
MDK

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 {RequestMethod}
Subhead {RequestURL}
SubStatus leave it empty
Title {HTTPStatusCode}
MDK

In Search section, update below properties:

Property Value
SearchEnabled true
MDK

In Behavior section, update below properties:

Property Value
AccessoryType disclosureIndicator
MDK

In EmptySection section, update below properties:

Property Value
Caption No Sync Errors Found
MDK
Log on to answer question
Step 3: Create a new page to display Error details

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.

MDK

Enter the Page Name as ErrorDetails and click Next and then Finish on the confirmation step.

MDK

In the Properties pane, set the caption to Error Details.

MDK

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 on the Rules folder | New | File.

MDK

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.

MDK

In the Properties | Target pane, click Object Browser icon, provide #Property:AffectedEntity in Expression box and click OK.

MDK

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
MDK

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

In Behavior section, update below properties:

Property Value
AccessoryType disclosureIndicator
MDK

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.

MDK

Now, bind its Caption property to GetAffectedEntityHeaderCaption.js file.

MDK

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.

MDK

Update NumberOfColumns value to 1.

MDK

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.

MDK

Provide the below information:

Property Value
KeyName HTTP Status Code
Value {HTTPStatusCode}
MDK

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:

MDK

More details on ErrorArchive Entity Properties is available in help documentation.

Save your changes to the Error Details page.

Log on to answer question
Step 4: Navigate from Error list page to Error details page

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

First, create a Navigation Action.

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

MDK

Provide the below information:

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

Next, 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 on the ShowErrorDetails.action action and click OK to set it as the OnPress Action.

MDK

Save your changes to the ErrorList.page file.

Log on to answer question
Step 5: Navigate from Error details page to affected record

When you click on 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.

First, create a Message Action to display this toast message.

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

MDK

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
MDK

Click Next and then Finish on the confirmation step.

Next, 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 on the Rules folder | New | File.

MDK

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.

Next, bind this file to onPress of Object Table in Error Details page.

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

Double click on the DecideWhichEditPage.js action and click OK to set it as the OnPress Action.

MDK

Save the changes to the ErrorDetails page.

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.

First, create a Navigation Action.

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

MDK

Provide the below information:

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

Next, on Main page, drag and drop the Section Button container onto the Page.

MDK

Provide Title as Error Archive.

MDK

Next, 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 on the ShowErrorList.action action and click OK to set it as the OnPress Action.

MDK

Save the changes to the Main page.

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 on the MDK Application in the project explorer pane and select MDK Deploy and Activate.

MDK

Let the default configuration as it is and click Next.

MDK

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

Externals is a list of NPM modules to be excluded from the bundle.

By default, automatically deploy option is selected, In other words, the application is automatically deployed from Mobile Services to your MDK client.

MDK

Based on the mobileservices_cf destination, you will find list of existing application IDs , select the one you have chosen while creating the project in step 1

MDK

Click Next to finish the deployment from SAP Web IDE.

You should see Application deployed successfully message in console log.

MDK
Log on to answer question
Step 8: Populate the QR code for app on-boarding

SAP Web IDE has a feature to generate QR code for app on-boarding.

Right click on the MDK Application in the project explorer pane and select MDK Deploy and Activate.

MDK

Let the default configuration as it is and click Next.

MDK

Click on QR code icon to populate QR code for app on-boarding.

MDK

Click on QR code icon to populate QR code for app on-boarding.

MDK
Log on to answer question
Step 9: Run the app in MDK client

Below steps & screenshots were captured with iOS device. You will have similar on-boarding experience with Android as well.

The MDK client receives deployed metadata definitions as a bundle.

Click Start to connect MDK client to SAP Cloud Platform.

MDK

Enter your SAP Cloud Platform credentials and click Log On to authenticate.

MDK

Agree on End User License Agreement.

MDK

Choose a passcode with at least 8 characters for unlocking the app and click Next.

MDK

Confirm the passcode and click Done.

MDK

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

MDK

Click OK.

MDK

Now, you will see Main page with some entity sets being displayed and Offline store is being initialized.

MDK

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, click either one of the record.

MDKMDK

Click Edit.

MDK

Make some changes to SupplierId value and Save it.

MDK

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.

MDK

Once you see Sync success message, navigate to Error Archive list.

MDK

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

MDK

Clicking 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 occured and in Request Body, it shows the property that caused this failure.

MDK

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.

Click Edit Affected Entity and modify record with correct values.

MDKMDK
What is AffectedEntity in context of this tutorial?
×

Next Steps

Prerequisites

Back to top