The Mashup SDK API includes the SnapStart module, which permits direct interaction with a connected Pega 7 Platform application from a native mobile Android app that is developed separately. After you sign in to the Pega 7 Platform instance, you can use the SnapStart module to create a case, open an existing case, show a harness, open an assignment, or run an activity. You accomplish these actions by using a single web view or multiple HTML web views within the native Android app.

• Prerequisites
• Obtaining the PRPCSnapStart object
• Adding event listeners
• Creating a case
• Opening a case by ID
• Showing a harness
• Opening an assignment
• Running an activity
• Additional options

Prerequisites

Before you continue, make sure that you have read the following information:

• Setting up the Mashup SDK for Android app development.
• Authenticating with Mashup SDK on Android article.
• Mashup SDK 1.0.0 JavaDocs, which describe the API.

Obtaining the PRPCSnapStart object

To use the SnapStart module in your Java code for the native Android app, you must call the constructor for the PRPCSnapStart object. This object, available on Android, is only a helper class that is built on top of WebView. Keep in mind that you have to create, manage, and display an instance of the HybridWebView class on your own. To do so, first obtain the HybridWebView object and call its init() method with a unique web view identifier, create a HybridWebViewClientDelegate and then instantiate the PRPCSnapStart object by using its constructor, passing the following three parameters:

• The authentication URL, as a String. Remember that the authentication URL is returned after you log in to the Pega 7 Platform instance. See Authenticating with Mashup SDK on Android.
• An instance of the HybridWebView object.
• An instance of the HybridWebViewClientDelegate.

To create multiple Mashup views, you need to manually create instances of HybridWebView with a unique name that is set by using a call similar to: webView.init("casesWebView"). Then, each HybridWebView should be used with a separate instance of the PRPCSnapStart object.

After you have an instance of the PRPCSnapStart object, you can use it in your Java code to create a case, open an existing case, show a harness, open an assignment, or run an activity by calling one of the SnapStart module functions. You can also use more than one HTML web view in your native Android application as long as each web view was initialized with a unique identifier string.

The following example shows how to obtain an instance of the PRPCSnapStart object in Java:
HybridWebView webView = new HybridWebView().init("caseWebView");
HybridWebViewClientDelegate delegate = new HybridWebViewClientDelegate() {
  public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
    // add code to handle error here
  }
};
prpcSnapStart = new PRPCSnapStart(authUrl, webView, delegate);

Adding event listeners

When using the SnapStart module, make sure to also add event listeners that take into account the following user actions:

• Submitting or canceling an action, that is, when a user closes the current window in the web view. The user should be taken back to the last native app screen that invoked the Pega 7 Platform web view.
• Logging out from the Pega 7 Platform instance.

For the first case, make sure to register the onWindowsClose() event listener on the PRPCSnapStart object for the previously initialized web view instance. For the second case, make sure to register the onUserLoggedOut() event listener on the PRPCSnapStart object for the previously initialized web view instance. The following Java code shows how to do this:

prpcSnapStart.registerEventListener(new EventListener() {
  public void onWindowClose() {
    // add code to handle window close
  }
  public void onUserLoggedOut() {
    // add code to handle logout
  }
}, "caseWebView" );

You can also add listeners without using an instance of the PRPCSnapStart object by calling the PrpcSnapStart.register() method. To unregister a listener, when, for example, an activity or a fragment is destroyed, make sure to also call PrpcSnapStart.unregisterEventListener() within the onDestroy() method. If you do not unregister a listener, a reference to the listener will be kept in the static field and cause a memory leak.

Creating a case

To create a case in the connected Pega 7 Platform instance within your native Android app, you must call the getCreateCaseRequestBuilder() method on the instance of the PRPCSnapStart object, passing it several parameters. See Additional options for a list of optional commands that you can also use when calling this method.

The following example shows the Java code for creating a case:

 prpcSnapStart.getCreateCaseRequestBuilder()
              .setInsClass("Wb-WBTest-Work-TestCase")
              .setFlowType("pyStartCase")
              .setPyShowFullPortal(false)
              .build()
              .load();

Opening a case by ID

To open an existing case by using an identifier in the connected Pega 7 Platform instance within your native Android app, you must call the getOpenCaseByHandleBuilder() method on the instance of the PRPCSnapStart object, passing it the parameter that is shown in the following table. See Additional options for a list of optional commands that you can also use when calling this method.

The following example shows the Java code for opening an existing case:

prpcSnapStart.getOpenCaseByHandleBuilder()
             .setInsHandle("Wb-Wbtest-Work T-1")
             .setPyShowFullPortal(false)
             .build()
             .load();

Showing a harness

To show a harness from the connected Pega 7 Platform instance within your native Android app, you must call the getShowHarnessBuilder() method on the instance of the PRPCSnapStart object, passing it several parameters. See Additional options for a list of optional commands that you can also use when calling this method.

The following example shows the Java code that displays a harness in read-only mode:

prpcSnapStart.getShowHarnessBuilder()
             .setClassName("Wb-WBTEST-WORK-TESTCASE")
             .setPurpose("UserDetails")
             .setReadOnly(true)
             .setPyShowFullPortal(false)
             .build()
             .load();

Opening an assignment

To open an assignment from the connected Pega 7 Platform instance within your native Android app, you must call the getOpenAssignmentRequestBuilder() method on the instance of the PRPCSnapStart object, passing it several parameters. See Additional options for a list of optional commands that you can also use when calling this method.

The following example shows the Java code that opens an assignment:

prpcSnapStart.getOpenAssignmentRequestBuilder()
             .setInsHandle("ASSIGN-WORKLIST WB-WBTEST-WORK T-17!OPEN")
             .setInsClass("Assign-")
             .setPyShowFullPortal(false)
             .build()
             .load();

Running an activity

To run an activity from the connected Pega 7 Platform instance within your native Android app, you must call the getRunActivityRequestBuilder() method on the instance of the PRPCSnapStart object, passing it several parameters. See Additional options for a list of optional commands that you can also use when calling this method.

The following example shows the Java code that runs an activity:

prpcSnapStart.getRunActivityRequestBuilder()
             .setPzActivity("TestActivity")
             .setPzActivityParams("test=Hello Mashup Developer!")
             .setPyShowFullPortal(false)
             .build()
             .load();

Additional options

When calling one of the SnapStart module methods on the PRPCSnapStart object to create, for example, a case or open an assignment, you can also pass the following optional parameters.

The following example shows the Java code that sets several additional options when you run an activity in the connected Pega 7 Platform instance:

prpcSnapStart.getRunActivityRequestBuilder()
             .setPzActivity("TestActivity")
             .setPzActivityParams("test=Hello Mashup Developer!")
             .setPyShowFullPortal(true)
             .setPyPhoneNavRuleMainVisible(true)
             .setPyTabletNavRuleToolbarVisible(false)
             .build()
             .load();