Next-generation platformDeprecated

Extending mashups

Edit online

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

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

Creating new mashups

Keep the following points in mind when creating new mashups:

  • The mashup XMLs should be placed in the respective module folder in the <isfwar>/extn/mashupxmls.
  • The file naming convention for mashups is: <module/component_name>_mashups.xml.
  • Keep files with names suffixed _mashups.xml and id like extn_ in the <runtime>/extensions/isf/webpages/mashupxmls/ folder.

Overriding mashups

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

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/mashupxmls/ directory.

The best practices to define a mashup XML are as follows:
  • It is best to prefix the mashup_id with extn_ and it should contain the entire component path to prevent mashup_id clashes between different mashups. For example. extn_isf.<module_name>.<component_name>.<task>
  • The init servlet that is required to load the incremental and override mashups is provided with the application and the servlet scans only the XML files in the <isfwar>/extn/mashupxmls folder.
  • You must restart the application server for the changes to take effect.
  • In your customization package, add the new mashups XMLs inside the <runtime>/extensions/isf/webpages/mashupxmls/ folder.

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 in 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>
Where,
  • 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 will have the RestURL as stores/<NodeId>/pick-requests/<pickRequestId>. Here, the mashup output contains PickRequest as the root element.

  • 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.

    All the mandatory input attributes such as mashuptype, RestEndPointConfigProperty, RestURL, and HTTPMethod must be passed 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

Rest mashups can be extended only by using Override Extensibility. Differential or incremental mashups extensibility is not supported. You can add custom mashup classes to your customization.

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 either of the following directories:
    • files/repository/eardata/isf/extn/WEB-INF/lib directory in your source control project
    • repository/eardata/isf/extn/WEB-INF/lib directory in developer toolkit runtime

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