Skip to main content

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

Use the SnapStart feature with the Mashup SDK on iOS

Suggest edit Updated on July 26, 2018

The Mashup SDK API includes the SnapStart feature, which permits direct interaction with a connected Pega 7 Platform application from a native mobile iOS 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 perform these actions by using one or more HTML web views within the native iOS app.

Prerequisites

Before you continue, read the following information:

Obtain the PMSnapStartViewController object

To use the Mashup SDK SnapStart feature in your Swift or Objective-C code for the native iOS app, you must initialize the PMSnapStartViewController object.

To create multiple Mashup views, you must create separate instances of the PMSnapStartViewController object. Each ViewController uses a separate instance of the HybridWebView object internally. Assign a unique name to each WebView by using a call similar to: snapStartController.webViewName = "caseWebView"(Swift) or snapStartController.webViewName = @"caseWebView"(Objective-C). You do not need to create a WebView instance manually. Everything is handled by the PMSnapStartViewController object, which is a fully functional ViewController that can be added directly to view the hierarchy.

After you obtain an instance of this object, use it in your Swift or Objective-C code to create a case; open an existing case, harness, assignment; or run an activity by calling a specific SnapStart function.

The following example shows how to obtain an instance of the PMSnapStartViewController object in Swift:

let snapStartController = PMSnapStartViewController() 
snapStartController.delegate = self 
snapStartController.webViewName = "caseWebView"

The following example shows how to obtain an instance of the PMSnapStartViewController object in Objective-C:

PMSnapStartViewController *snapStartController = [[PMSnapStartViewController alloc] init]; 
snapStartController.delegate = self; 
snapStartController.webViewName = @"caseWebView";

You can call the performAction() method immediately after initializing the PMSnapStartViewController object and passing the activity to it. Invoking this method creates a web view in the background and starts to load the content. The performAction() method is used to preload the content so that the user is not presented with an initial blank screen in their mobile app. When the didPerformAction() delegate method is invoked, the PMSnapStartViewController object has finished loading.

Add delegate methods

When you use the SnapStart module, make sure to also add delegate methods that include submitting or canceling an action, such as when a user closes the current window in the web view. The user should be returned to the last native app screen that invoked the Pega 7 Platform web view.

Make sure to register the didFinishAction: delegate.

See the following Swift code for an example:

func snapStartController(controller: PMSnapStartViewController, didStartAction action: PMSnapStartAction) { 
// add code to handle a situation when the first screen was started or the first step of the action was loaded 
} 
func snapStartController(controller: PMSnapStartViewController, didFailAction action: PMSnapStartAction, withError error: NSError) { 
// add code to handle failures that occur while running action 
} 
func snapStartController(controller: PMSnapStartViewController, didFinishAction action: PMSnapStartAction) { 
// add code to handle a situation when an action is finished, in other words, the SnapStart window is closed 
}

See the following equivalent Objective-C code for an example:

- (void)snapStartController:(PMSnapStartViewController *)controller didStartAction:(PMSnapStartAction *)action { 
// add code to handle a situation when the first screen was started or the first step of the action was loaded 
} 
- (void)snapStartController:(PMSnapStartViewController *)controller didFailAction:(PMSnapStartAction *)action withError:(NSError *)error { 
// add code to handle failures that occur while running action 
} 
- (void)snapStartController:(PMSnapStartViewController *)controller didFinishAction:(PMSnapStartAction *)action { 
// add code to handle a situation when an action is finished, in other words, the SnapStart window is closed 
}

Create a case

To create a case in the connected Pega 7 Platform instance from within your native iOS app, you must first create an instance of the PMCreateCaseAction object by calling the initWithPortalURL:insClass: method and passing several parameters to it, as shown in the following table.

ParameterDescriptionType

insClass
(required)

Class name of the work type (case type).NSString
flowType
(required)
Name of the flow to run.NSString
portalURL
(required)
The URL pointing to a Pega 7 Platform instance.NSURL

Next, call the performAction: method on the instance of the PMSnapStartViewController object, passing the create case object to it as a parameter.

The following example shows the Swift code that creates a case:

let portalURL = NSURL(string: "portalURL") 
let createCase = PMCreateCaseAction(portalURL: portalURL, flowType: "pyStartCase", insClass:"Wb-WBTest-Work-TestCase") 
snapStartController.performAction(createCase)

The following example shows the equivalent Objective-C code that creates a case:

NSURL *portalURL = [NSURL URLWithString:@"portalURL"]; 
PMCreateCaseAction *createCase = [[PMCreateCaseAction alloc] initWithPortalURL:portalURL flowType:@"pyStartCase" insClass:@"Wb-WBTest-Work-TestCase"]; 
[snapStartController performAction:createCase];

Open a case by ID

To open an existing case in the connected Pega 7 Platform instance from within your native iOS app, you must first create an instance of the PMOpenCaseByIdAction object by calling the initWithPortalURL:insHandle: method, passing a parameter as shown in the following table.

ParameterDescriptionType

insHandle
(required)

The identifier of the case (pzInsKey).NSString
portalURL
(required)
The URL pointing to a Pega 7 Platform instance.NSURL

Next, call the performAction: method on the instance of the PMSnapStartViewControllerobject, passing the open case object to it as a parameter.

The following example shows the Swift code that opens an existing case:

let portalURL = NSURL(string: "portalURL") 
let openCase = PMOpenCaseByIdAction(portalURL: portalURL, insHandle: "WB-WBTEST-WORK T-24") 
snapStartController.performAction(openCase)

The following example shows the equivalent Objective-C code that opens an existing case:

NSURL *portalURL = [NSURL URLWithString:@"portalURL"]; 
PMOpenCaseByIdAction *openCase = [[PMOpenCaseByIdAction alloc] initWithPortalURL:portalURL insHandle:@"WB-WBTEST-WORK T-24"]; 
[snapStartController performAction:openCase];;

Show a harness

To show a harness from the connected Pega 7 Platform instance within your native iOS app, you must first create an instance of the PMOpenHarnessAction object by calling the initWithPortalURL:purpose:className: method and passing several parameters to it, as shown in the following table.

ParameterDescriptionType
harnessTarget (required)The destination of the harness. By default, it is always set to "newDocument", so you do not have to use it in your call. However, if needed, you can change it to another value.NSString

className (required)

The class that the harness belongs to. If you use pzMobileInitActivity, then:

  • This is the class of that activity.
  • The class of the harness is the class of the page (pzMobileContextPageName) that is created by this activity.
NSString
purpose (required)The name of the harness.NSString
portalURL (required)The URL that points to a Pega 7 Platform instance.NSURL

After you have an instance of PMOpenHarnessAction, you can set the following additional optional parameters on this object:

ParameterDescriptionType
readOnly
(optional)
Makes the harness read-only. Default value is false.BOOL
pzMobileInitActivity
(optional)

The name of activity to be called to initialize data. Keep in mind that:

  • This is only the activity name.
  • The class is defined in the className parameter.
NSString
pzMobileContextPageName
(optional)

The name of the page that the activity works on and that the showHarness is opened against. Keep in mind that:

  • This parameter is required if you also use the PzMobileInitActivity parameter in the call.
  • For example, if you want your harness to show report data, you could name your page "reportPage". In your activity, you would create "reportPage" and fill it with report data. The harness is then displayed by using "reportPage".
NSString

Next, call the performAction: method on the instance of the PMSnapStartViewControllerobject, passing the open harness object to it as a parameter.

The following Swift code example shows a read-only harness:

let portalURL = NSURL(string: "portalURL") 
let openHarness = PMOpenHarnessAction(portalURL: portalURL, purpose: "UserDetails", className:"WB-WBTEST-WORK-TESTCASE") 
openHarness.readOnly = true 
snapStartController.performAction(openHarness)

The following equivalent Objective-C code example shows a read-only harness:

NSURL *portalURL = [NSURL URLWithString:@"portalURL"]; 
PMOpenHarnessAction *openHarness = [[PMOpenHarnessAction alloc] initWithPortalURL:portalURL purpose:@"UserDetails" className:@"WB-WBTEST-WORK-TESTCASE"]; 
openHarness.readOnly = YES; 
[snapStartController performAction:openHarness];

Open an assignment

To open an assignment in the connected Pega 7 Platform instance from within your native iOS app, you must create an instance of the PMOpenAssignmentAction object by calling the initWithPortalURL:insHandle:insClass: method and passing several parameters to it, as shown in the following table.

ParameterDescriptionType

insHandle
(required)

The assignment instance handle (pzInsKey).NSString
insClass
(required)
The class of the assignment, which often consists of "Assign-".NSString
portalURL
(required)
The URL pointing to a Pega 7 Platform instance.NSURL

Next, call the performAction: method on the instance of the PMSnapStartViewControllerobject, passing the open assignment object to it as a parameter.

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

let portalURL = NSURL(string: "portalURL") 
let openAssignment = PMOpenAssignmentAction(portalURL: portalURL, insHandle: "ASSIGN-WORKLIST WB-WBTEST-WORK T-17!OPEN", insClass:"Assign-" 
snapStartController.performAction(openAssignment)

The following example shows the equivalent Objective-C code that opens an assignment:

NSURL *portalURL = [NSURL URLWithString:@"portalURL"]; 
PMOpenAssignmentAction *openAssignment = [[PMOpenAssignmentAction alloc] initWithPortalURL:portalURL insHandle:@"ASSIGN-WORKLIST WB-WBTEST-WORK T-17!OPEN" insClass:@"Assign-"]; 
[snapStartController performAction:openAssignment];

Run an activity

To run an activity in the connected Pega 7 Platform instance from within your native iOS app, you must create an instance of the PMRunActivityAction object by calling the initWithPortalURL:pzActivity: method and passing several parameters to it, as shown in the following table.

ParameterDescriptionType

pzActivity
(required)

The name of activity to run. Keep in mind that:

  • It uses the "activityName" or "className.activityName" form.
  • With no class, it is either "@baseclass" or the class of the pzPrimaryPageName.
NSString
pzPrimaryPageName
(optional)
The name of the page for the activity to work on.NSString
portalURL
(required)
The URL that points to a Pega 7 Platform instance.NSURL

Next, call the performAction: method on the instance of the PMSnapStartViewController object, passing the run activity object to it as a parameter.

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

let portalURL = NSURL(string: "portalURL") 
let runActivity = PMRunActivityAction(portalURL: portalURL, pzActivity: "TestActivity") 
snapStartController.performAction(runActivity)

The following example shows the equivalent Objective-C code that runs an activity:

NSURL *portalURL = [NSURL URLWithString:@"portalURL"]; 
PMRunActivityAction *runActivity = [[PMRunActivityAction alloc] initWithPortalURL:portalURL pzActivity:@"TestActivity"]; 
[snapStartController performAction:runActivity];

Additional properties

When calling one of the SnapStart functions on the PMSnapStartViewController object, for example, to create a case or open an assignment, you can also set additional optional properties, as described in the following table.

PropertyDescriptionType

pyShowFullPortal
(optional)

If set to true, the target content is loaded with the surrounding portal navigation.

If set to false the target content is not loaded with the surrounding portal navigation.

NSNumber
pyPhoneNavRuleMainVisible (optional)

If set to true, the main navigation is visible on a phone device.

If set to false, it is not visible on a phone device.

NSNumber
pyTabletNavRuleMainVisible (optional)

If set to true, the main navigation is visible on a tablet device.

If set to false, it is not visible on a tablet device.

NSNumber
pyPhoneNavRuleToolbarVisible (optional)

If set to true, the toolbar is visible on a phone device.

If set to false, it is not visible on a phone device.

NSNumber
pyTabletNavRuleToolbarVisible (optional)

If set to true, the toolbar is visible on a tablet device.

If set to false, it is not visible on a tablet device.

NSNumber
snapStartParameters (optional)Additional parameters that are passed as a value of a SnapStart parameter.[String:String]?
customURLParameters (optional)Additional query string parameters that are passed in the URL.[String:String]?

The following example shows the Swift code that sets several properties for the run activity object:

runActivity.pyShowFullPortal = true 
runActivity.pyPhoneNavRuleMainVisible = true 
runActivity.pyTabletNavRuleToolbarVisible = false 
runActivity.snapStartParameters = ["key1" : "value1", "key2" : "value2"] 
runActivity.customURLParameters = ["key1" : "value1", "key2" : "value2"] 
snapStartController.performAction(runActivity)

The following example shows the equivalent Objective-C code that sets several properties for the run activity object:

runActivity.pyShowFullPortal = [NSNumber numberWithBool:YES]; 
runActivity.pyPhoneNavRuleMainVisible = [NSNumber numberWithBool:YES]; 
runActivity.pyTabletNavRuleToolbarVisible = [NSNumber numberWithBool:NO]; 
runActivity.snapStartParameters = @{ @"key1" : @"value1", @"key2" : @"value2" }; 
runActivity.customURLParameters = @{ @"key1" : @"value1", @"key2" : @"value2" }; 
[snapStartController performAction:runActivity];

Related articles

Mashup SDKSetting up the Mashup SDK for iOS app developmentAuthenticate with the Mashup SDK on iOS

Tags

Pega Platform 7.2.1 Pega Mobile Mashup Mobile Pega Express Media and Advertising Utilities Financial Services Government Healthcare Insurance Life Sciences Manufacturing Retail Hospitality and Entertainment
Did you find this content helpful? YesNo

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.

Ready to crush complexity?

Experience the benefits of Pega Community when you log in.

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us