Next-generation platform

Extending mashups

Edit online

Mashups are used to invoke XAPIs on the server and return data to the UI layer. You can create new mashups or extend mashups to suit your business needs.

For more information about the mashup layer, see Working with mashups.

Creating mashups

For the new custom mashups, follow these guidelines:
  • Save custom mashups in the <runtime>/extensions/isf/webpages/mashupxmls/ folder. Ensure that you suffix the file name with _mashups.xml.
  • The naming convention for the mashup ID must be extn_isf.<module_name>.<component_name>.<task>.
  • If you want to verify the mashup changes for testing, complete any one of the following steps based on your environment.
    In on premises environments, complete the following steps:
    1. Build and update the EAR file in the application server.
    2. Run app server restart for the changes to take effect.
    In DTK environments, complete the following steps:
    1. Update the extension jar with the mashup changes.
    2. Run ./om-compose.sh update-extn <full path to extensions.jar>.

Overriding mashups

To manually extend an application-provided mashup by using the override extensibility, copy the existing mashups into files with names suffixed _overridemashups.xml in the <runtime>/extensions/isf/webpages/mashupxmls/ directory.

If you want to verify the mashup changes for testing, complete any one of the following steps based on your environment.
  • In on premises environments, complete the following steps:
    1. Build and update the EAR file in the application server.
    2. Run app server restart for the changes to take effect.
  • In DTK environments, complete the following steps:
    1. Update the extension jar with the mashup changes.
    2. Run ./om-compose.sh update-extn <full path to extensions.jar>.

Incrementing mashups

To extend mashups incrementally, when you need attributes to be added to the mashup input or output, copy the existing mashup into files with names suffixed _incrementalmashups.xml in the <runtime>/extensions/isf/webpages/mashupxmls/ directory.

If you want to verify the mashup changes for testing, complete any one of the following steps based on your environment.
  • In on premises environments, complete the following steps:
    1. Build and update the EAR file in the application server.
    2. Run app server restart for the changes to take effect.
  • In DTK environments, complete the following steps:
    1. Update the extension jar with the mashup changes.
    2. Run ./om-compose.sh update-extn <full path to extensions.jar>.

Calling REST APIs from the mashup layer

Generally, mashups are used to invoke XAPIs on the server and return data to the UI layer. You can extend mashups to suit your business needs.

Mashups can also be used to make REST calls to any REST end point. This capability is used when after the REST call, an Sterling Order Management System API call needs to be made in the same network call.

For example, the flow to pick products by using the Sterling Store Engagement UI needs to display product details such as SKU ID, description, and product image along with the Pick Request details. For this scenario, Get Pick request call on Store Inventory Management microservice is made and the REST API output can be massaged to append Item Information by calling getItemList API in the custom mashup class.

The following sample code snippet shows how to define the mashup XML:
<mashup description="Create a pick request in SIM" endpoint="SIM"
		id="isf.backroompick.pick-order.createPickRequest" mashuptype="REST" transactional="true" skipDataProvider="true">
		<classInformation name="com.ibm.isf.common.mashups.ISFRestBaseMashup" />
		<API Name="pick-requests">
			<Input>
				<RESTData HTTPMethod="POST"  RestURL="" RestEndPointConfigProperty="">
					<Input referenceId="" assignedToUserId="" stagingLocationId="" draft="">
					    <requestedProducts productId="" unitOfMeasure="" productClass="" requestedQuantity=""/>
					</Input>
				</RESTData>
			</Input>
			<Template>
				<PickRequest/>
			</Template>
		</API>
		<APINamespace inputNS="createPickRequest_input" outputNS="createPickRequest_output" />
		<AlternateResourceIds>
			<AlternateResourceId altResourceId="ISFSYS00001"/>
            <AlternateResourceId altResourceId="ISF000001"/>
            <AlternateResourceId altResourceId="ISF000002"/>
		</AlternateResourceIds>
   </mashup>
Here,
  • mashuptype: Specifies whether the mashup makes XAPI or REST API call. Valid values are XAPI and REST.
  • classInformation: REST mashups must use com.ibm.isf.common.mashups.ISFRestBaseMashup as BaseMashup while XAPI calls uses com.ibm.isf.common.mashups.
  • ISFBaseMashupRestEndPointConfigProperty: Specifies the yfs property that can be used to retrieve the REST end point.

    For Store Inventory Management microservice, the yfs property to use is yfs.sim.endpointurl.

    For example, RestEndPointConfigProperty="yfs.sim.endpointurl"

  • RestURL: Specifies the URL that needs to be invoked for a particular API.

    For example, GET call to fetch pick request details by using pickRequestId contains the RestURL as stores/<NodeId>/pick-requests/<pickRequestId>. Here, the mashup output contains PickRequest as the root element name.

  • HTTPMethod: Specifies the HTTP method that is used for making the REST call.
  • Input Element: Used as request Body for making HTTP POST/PATCH/PUT calls. This element is not required for GET/DELETE calls.
  • Template: The child element name of the Template element is the root element of mashup output.
    Note: Store Inventory Management microservice REST API outputs are not template controlled. Hence, REST mashups are also not template controlled.

    You must pass all the mandatory input attributes such as mashuptype, RestEndPointConfigProperty, RestURL, and HTTPMethod from the UI. Unlike XAPI mashups, defining the value of an attribute in the mashup XML does not merge it before making the API calls. Also, session objects such as CurrentUser and CurrentStore are not read for REST mashups.

Extending REST mashups

You can extend Rest mashups by using Override Extensibility.

Note: IBM does not support extensibility of differential or incremental mashups.

For more information about building and deploying your customizations, see Building and deploying your customizations.

Packaging custom mashup classes

To add the custom mashup classes as part of your customizations:
  1. Create a JAR file for your custom mashup classes.
  2. Copy the JAR file to any one of the following directories:
  3. In the extensions JAR file, ensure that the JAR file that contains the custom class must be present in the extensions/files/repository/eardata/isf/extn/WEB-INF/lib directory.