The Mashup SDK API includes the SnapStart feature, 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 SnapStart to create a case; open an existing case, harness, or 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
• Obtain the SnapStart object
• Add event listeners
• Make a SnapStart request
• Create a case
• Open a case by ID
• Show a harness
• Open an assignment
• Run 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.
• Authenticate with Mashup SDK on Android.
• Mashup SDK JavaDocs, which describe the API.

Obtain the SnapStart object

To use the SnapStart feature in your Java code for the native Android app, you must call the constructor for the SnapStart object. This object, available on Android, is a helper class that is independent of theHybridWebViewobject. If you plan to run SnapStart actions together with a web view, you have to create, manage, and display an instance of the HybridWebView class on your own. You can create a HybridWebView object by either calling its constructor:

HybridWebView webView = new HybridWebView( context, "caseWebView" );

or by adding this object directly in the XML layout and later retrieving it by using the findViewById() method for the Android activity:

<com.pega.mobile.webview.HybridWebView  
android:id="@+id/webview"  
custom:name="Pega7"  
android:paddingLeft="@dimen/activity_horizontal_margin"  
android:paddingRight="@dimen/activity_horizontal_margin"  
android:paddingTop="@dimen/activity_vertical_margin"  
android:paddingBottom="@dimen/activity_vertical_margin"  
android:layout_height="fill_parent"  
android:layout_width="fill_parent"/>

The following example shows how to obtain an instance of the SnapStart object in Java. You pass the authentication URL, as a string, to the SnapStart object constructor.

SnapStart snapStart = new SnapStart( authUrl );

Add event listeners

When using SnapStart, make sure to also add event listeners that include submitting or canceling an action, such as 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. You must define the WebViewLoadingListener class for this purpose, and pass it as the third parameter when calling the executeSnapStartRequest() method. See the following Java code for an example:

private class WebViewLoadingListener extends SnapStartWebViewListener {  
  @Override  
  public void onActionFinished() {  
    getActivity().onBackPressed();  
  }  
  
  @Override  
  public void onActionStarted(SnapStartRequest request) {  
    if (timerHandler != null) {  
      timerHandler.removeCallbacks(timeoutRunnable);  
    }  
    timerHandler = null;  
  
    if (getStartedPressed) {  
      hideLoading();  
    }  
    webViewLoaded = true;  
  }  
  
  @Override  
  public void onActionFailure(SnapStartRequest request, SnapStartError error) {  
    showAlert();  
  }  
  
  private void showAlert() {  
    if (timerHandler != null) {  
      timerHandler.removeCallbacks(timeoutRunnable);  
    }  
    timerHandler = null;  
    timeoutRunnable.run();  
  }  
}  
SnapStartRequest request = snapStart.getCreateCaseRequestBuilder()  
.build();  
snapStart.executeSnapStartRequest(request, webView, new WebViewLoadingListener() );

Make a SnapStart request

After you have created an instance of the SnapStart object, you can use it in your Java code to create a case; open an existing case, harness, or assignment; or run an activity by calling the executeSnapStartRequest() method for this object passing instances of the SnapStartRequest, HybridWebView, and WebViewLoadingListener objects, as its parameters. See the following Java code for example:

SnapStartRequest request = snapStart.getCreateCaseRequestBuilder()  
.build();  
snapStart.executeSnapStartRequest( request, webView, new WebViewLoadingListener() );

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. To create multiple Mashup views, you must manually create instances of HybridWebView with a unique name that is passed as the second parameter in the executeSnapStartRequest() method. Each HybridWebView should be used with a separate instance of the SnapStart object.

Create a case

To create a case in the connected Pega 7 Platform instance within your native Android app, you must create an instance of the SnapStartRequest object. To do so, you must call the getCreateCaseRequestBuilder() method on the instance of the SnapStart object, and pass several parameters to it. See Additional options for a list of optional commands that you can use when calling this method. Once you obtain an instance of the SnapStartRequest object, you use it as the first parameter when calling the executeSnapStartRequest() method on the SnapStart instance.

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

SnapStartRequest request = snapStart.getCreateCaseRequestBuilder()  
.setInsClass("Wb-WBTest-Work-TestCase")  
.setFlowType("pyStartCase")  
.setPyShowFullPortal(false)  
.build();  
snapStart.executeSnapStartRequest( request, webView, new WebViewLoadingListener() );

Open 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 create an instance of the SnapStartRequest object. To do so, you must call the getOpenCaseByHandleBuilder() method on the instance of the SnapStart object, and pass the parameter to it that is shown in the following table. See Additional options for a list of optional commands that you can use when calling this method. Once you obtain an instance of the SnapStartRequest object, you use it as the first parameter when calling the executeSnapStartRequest() method on the SnapStart instance.

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

SnapStartRequest request = snapStart.getOpenCaseByHandleBuilder()  
.setInsHandle("Wb-Wbtest-Work T-1")  
.setPyShowFullPortal(false)  
.build();  
snapStart.executeSnapStartRequest( request, webView, new WebViewLoadingListener() );

Show a harness

To show a harness from the connected Pega 7 Platform instance within your native Android app, you must create an instance of the SnapStartRequest object. To do so, you must call the getShowHarnessBuilder() method on the instance of the SnapStart object, and pass several parameters to it. See Additional options for a list of optional commands that you can use when calling this method. Once you obtain an instance of the SnapStartRequest object, you use it as the first parameter when calling the executeSnapStartRequest() method on the SnapStart instance.

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

SnapStartRequest request = snapStart.getShowHarnessBuilder()  
.setClassName("Wb-WBTEST-WORK-TESTCASE")  
.setPurpose("UserDetails")  
.setReadOnly(true)  
.setPyShowFullPortal(false)  
.build();  
snapStart.executeSnapStartRequest( request, webView, new WebViewLoadingListener() );

Open an assignment

To open an assignment from the connected Pega 7 Platform instance within your native Android app, you must create an instance of the SnapStartRequest object. To do so, you must call the getOpenAssignmentRequestBuilder() method on the instance of the SnapStart object, and pass several parameters to it. See Additional options for a list of optional commands that you can use when calling this method. Once you obtain an instance of the SnapStartRequest object, you use it as the first parameter when calling the executeSnapStartRequest() method on the SnapStart instance.

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

SnapStartRequest request = snapStart.getOpenAssignmentRequestBuilder()  
.setInsHandle("ASSIGN-WORKLIST WB-WBTEST-WORK T-17!OPEN")  
.setInsClass("Assign-")  
.setPyShowFullPortal(false)  
.build();  
snapStart.executeSnapStartRequest( request, webView, new WebViewLoadingListener() );

Run an activity

To run an activity from the connected Pega 7 Platform instance within your native Android app, you must create an instance of the SnapStartRequest object. To do so, you must call the getRunActivityRequestBuilder() method on the instance of the SnapStart object, and pass several parameters to it. See Additional options for a list of optional commands that you can use when calling this method. Once you obtain an instance of the SnapStartRequest object, you use it as the first parameter when calling the executeSnapStartRequest() method on the SnapStart instance.

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

Map<String, String> parameters1 = new HashMap();  
parameters1.put("test","Hello Mashup Developer!");  
SnapStartRequest request = snapStart.getRunActivityRequestBuilder()  
.setPzActivity("TestActivity")  
.setPyShowFullPortal(false)  
.setSnapStartParameters(parameters1)  
.build();  
snapStart.executeSnapStartRequest( request, webView, new WebViewLoadingListener() );

Additional options

When calling one of the SnapStart methods on the SnapStart object to create, for example, a case or to 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:

Map<String, String> parameters1 = new HashMap();  
parameters1.put("key1","value1");  
parameters1.put("key2","value2");  
Map<String, String> parameters2 = new HashMap();  
parameters2.put("key3","value3");  
parameters2.put("key4","value4");  
SnapStartRequest request = snapStart.getRunActivityRequestBuilder()  
.setPzActivity("TestActivity")  
.setPyShowFullPortal(true)  
.setPyPhoneNavRuleMainVisible(true)  
.setPyTabletNavRuleToolbarVisible(false)  
.setSnapStartParameters(parameters1)  
.setCustomParameters(parameters2)  
.build();  
snapStart.executeSnapStartRequest( request, webView, new WebViewLoadingListener() );