Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Creating a mashup

Updated on December 13, 2022
Applicable to Theme Cosmos applications

Enhance the functionality of your web application by embedding elements of Pega UI in your code. You can render whole cases so that users can create work and manage assignments. For example, you can embed a feedback form within your website so that the users who access the page can share their comments.

Before you begin: Complete the following actions:

    Generating the mashup code in App Studio

  1. In the navigation pane of App Studio, click Channels.
  2. In the Create new channel interface section, click Web mashup.
  3. On the New Web mashup interface form, in the Basic options section, in the Name field, enter a name for the mashup.
    For example: Enter Feedback item.
  4. Optional: To distinguish this channel interface from other mashup channel interfaces, in the Description field, specify the purpose of this channel interface.
    For example: Enter Case type for user feedback.
  5. In the URL field, enter the URL for your mashup:
    • If you want the user to open the default application for their operator record, use the URL pattern.
    • If you want the user to access a specific application, use the<application alias> URL pattern.
    • If your application uses an authentication service and you want the user to open the default application for their operator record, use the<authentication service alias> URL pattern.
    • If your application uses an authentication service and you want the user to access a specific application, use the<application alias>/<authentication service alias> URL pattern.
    • Because some users might have access to several applications in their operator record, the best practice is to always use application aliases with mashups. For more information, see Adding an application URL alias.
    • Mashups support all Pega authentication services only when the URL syntax in the data-pega-url attribute is correct. For more information, see Mashup attributes.
  6. Optional: To generate the mashup snippet with URL encryption, turn on the Use encryption switch.
    Note: When the Use encryption switch is on, dynamic parameters are not supported.
  7. In the Configuration section, in the Action list, select an action for the mashup.
    For example: Select Create a new case.
  8. Depending on the selected action, complete the relevant settings:
    Create a new caseIn the Case type drop-down menu, select the required case type.
    Display a page
    1. In the Class field, select the required class.
    2. In the Harness field, select the required harness.
    3. Optional: To use a data transform, in the Data transform field, select a required data transform.
    4. Optional: To block the page from editing, turn on the Read only switch.
    Get next workNone
    Open an assignmentIn the Param key field, enter the required assignment key.
    Open a case by IDIn the Work ID field, enter the required work object ID.
    Open a case by HandleIn the Param key field, enter the required work object handle.
    Open a case by URLIn the Query param field, enter the required query parameter. For example, to define a custom activity, you can use pyActivity=ClassName.activityName&Parameter1=ParameterValue1&Parameter2=ParameterValu
    Note: Loading a full Portal in a mashup is not recommended.
    For example: For the Create a new case action, in the Case type list, select the Creating a feedback item case type.
    Sample configuration for the feedback case type
    The configuration section with the completed fields for the Create a new feedback item case type.
  9. In the Thread name field, enter a name for the thread that handles the mashup.
  10. Optional: To defer the load of the mashup gadget, turn on the Defer mashup load switch, and then, in the page script, configure the initiation of the mashup loading process based on your preference.
    For example: You can make the mashup available to the application users after they click a button on the page to open the feedback form.
  11. Optional: To retain the state of the case after the user refreshes the browser that displays the mashup, turn on the Retain mashup state on browser refresh switch.
    Note: Consider the following limitations when you use this option:
    • The option is not backward-compatible with earlier versions of Pega Platform by default.
    • The option works only if the user loads the mashup gadget on the same thread, and the thread is available during a browser refresh. This setting does not work if the user sets the thread name dynamically while loading the mashup.
    • The state is retained if the refresh occurs in the same session.
    • The option to retain the case state does not work for temporary work objects, for which the system does not generate work IDs.
  12. Optional: To validate a mashup gadget request that has dynamic parameters in the mashup code, turn on the Allow passing dynamic parameters switch.
    Dynamic parameters are any parameters that you put in the mashup code on the external page. For example, if you have a custom parameter called CustomerID and you want to pass the value for this parameter, which is based on the ID of the user who visits the page, you include the parameter on the external page, which makes the parameter dynamic. Static parameters are all the parameters that the system generates with the mashup code.
    Note: Selecting this checkbox allows you to pass unregistered mashup parameters.
  13. Configure the output options for the mashup:
    1. In the Skin list, select the skin rule that you want to use for the mashup.
    2. In the Iframe resizing list, select the resize mode for the mashup.
    3. In the Initial skeleton list, select the skeleton to provide a template for the mashup.
      Tip: You can check how the skeleton renders the content by clicking Skeleton preview.
      Sample mashup configuration for the feedback case type
      New Web mashup interface form with the required setup for the Creating a feedback item case type
  14. Optional: To add a custom parameter, in the Custom parameters section, click the Add a row icon, and then enter the parameter name and value.
  15. In the What is a mashup section, click Generate mashup code, and then, in the Mashup code window, select the type of code that you want to copy:
    • To copy the iFrame code, above the iframe code window, click Copy.
    • To copy the mashup code, above the Mashup code window, click Copy.
    Note: Selecting the iframe code improves the response time of a mashup, but does not support passing dynamic parameters.
    Required mashup code
    A dialog box displaying the required Pega HTML to copy
  16. Close the Mashup code window.
  17. Click Save.
  18. Optional: To preview how different devices display the mashup code, in App Studio, click Preview application, and then select the channel that you want to preview by clicking the channel name next to the application name.
  19. Deploying the mashup on an external web page by pasting the mashup <div> code into the code of the host site

  20. Paste the code that you copied from the Mashup code window into a static web page or webview of an external web application to display your embedded case.
    At run time, the page HTML includes the mashup code as shown in the following example:

    <!DOCTYPE HTML PUBLIC "-//example//443 HTML 4.01 Transitional//EN" ""> 
    <html lang="en">
          <meta http-equiv="content-type" content="text/html; charset=utf-8">
          <title>Pega Web Mashup Page</title>
          <p>This page will host a Pega Web Mashup</p>
          <!-- ********************** Begin Pega content ********************** --> <script src ='*'></script> 
          <div data-pega-encrypted ='true' data-pega-encrypted-hash = 'pzuiactionzzz=CXtpbn1paGFRZ3UrMUpldm1LaEVTaVVGTW13UGt6VlZqNnRWcFRqTmNJbUdBU0lFbS9RSVNkV0NqYkI0YTVMVXhMT2lHYlRUUDQ2YStSZUZxS2tmQ1R0YUd2dXVBQnpiaDNpcis1akc2dUNrRndiT254eTgwZ3Rud0tMb1BtcnZrQXNicVRwWXFHY0hnNlZKNFVhNytsdXJPQUFVYWV2QVVGL21xN0ErZ2RDR0p3L1NsZlZUYXd5ZUduVkdxWXRSaXZza24rYnlneFRkY0ZFUkdZaHZtS2RaVGs0ODlnZWszRldWUE5tWURzYWsxS2RxNk9aOHIreG5sVExGZ1UrdTdZU1Njc2xXU25mMWRhTXFpVGJPbGVHTDB2UFJFdURiQnAwMzV1KytDcXBWQ1RSVUptcStSKzVrcTM4UE9TckZIcVZSSGxzM04yZzlrLytmM051RHZWRGJzK1E1NmF4bzViQWNzSWpYSFRpL3pMa0RKQ3E0bUJoNkYyc2hobWtTeHdGdkJoUERWSGhtMEorOEM3dUxPNjMzQWhBPT0%3D*' data-pega-gadgetname ='PegaGadget' data-pega-action ='createNewWork' data-pega-action-param-classname ='O4VO4O-MyApplication-Work-CreatingAFeedbackItem' data-pega-action-param-flowname ='' data-pega-isretained ='true' data-pega-isdeferloaded ='false' data-pega-applicationname ='MyApplication' data-pega-threadname ='Feedbackitem' data-pega-channelID ='MASHUP72ca358325894a7fa91fb3ff6b5d6a' data-pega-resizetype ='stretch' data-pega-url ='' data-pega-action-param-parameters ='{"pzSkinName":"pyEndUser_Mantis","pyMashupSkeletonName":"pyDefaultMashupSkeleton","UserIdentifier":"MashupUser","Password":"Password"}' ></div>
          <!-- ********************** End Pega content ********************** --> 
  21. Optional: To put multiple mashups on a single web page, include the mashup static script pzIncludeMashupScripts in the HTML code only once.
  22. Configuring the application permissions to allow your application to accept incoming messages from the host site

  23. In Dev Studio, click Application nameDefinition, and then click the Integration & security tab to configure the application permissions by specifying a list of trusted domains in the Pega Platform application rule.
    The list contains the URLs on which you are deploying the mashup. Ensure that you include the site that you intend to use to test the mashup. For more information, see Securing your application for mashup communication.
  24. In the Mashup security section, in the list of trusted origins (URLs), click Add a row, and then enter a URL that can access your application.
    The list contains the URLs on which you are deploying the mashup. List only the origins you trust to use Pega Web Mashup gadgets from this application. Specify the host, port, and protocol for each of your websites, for example:
    Note: port # is optional for well-known ports.

    The list of trusted URLs
    The list of trusted origins with a selected URL that can access the application. Here, the URL is
  25. Click Save.
Result: When you next load your host site, the application is displayed in an iframe of the page.
For example:
The feedback item embedded in a host page
An external page with the embedded feedback item mashup

Have a question? Get answers now.

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

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us