Adding search fields to existing search pages

Edit online

Understand and learn the search_fields.json syntax that defines the search fields to display in the user interface. You can add search fields such as radio buttons, text inputs, drop down menus, and date pickers to include more parameters in the search query.

As a reference, the following tutorial adds search fields to existing search pages: Tutorial: Customizing the Create order flow.

Table of contents

JSON file locations

Update or create the JSON file within the module's src-custom/assets/custom folder. For example, packages/<route>/src-custom/assets/custom/search_fields.json.

If there are no additional customizations required other than the changes in the JSON file, the JSON file does not need to be associated to any route. Instead, create the JSON file under packages/<app>-root-config/src/assets/custom/search_fields.json. Doing so ensures that future Order Hub releases are automatically applied without manually synchronizing your customization code.
Note: This approach does not require updating routes in the package-customization.json file during deployment.

JSON syntax

When constructing JSON for new customized fields, do not use the syntax from the default search_fields.json file in the source code. Instead use the following syntax:
  • The main JSON body contains uniquely defined object attributes that map to different modules.
    • orders is the module for the Order search pages.
    • shipments is the module for the Shipment search pages.
    • nodes is the module for the Node search page.
    • alerts is the module for the Alerts search page.
  • Each object contains a fields array that includes attributes.

Attributes

label
A label for the search field.
Type
The type of search field. You can set the attribute to one of the following values:
addressPicker
User can search for and select an address.
Image of address picker
date
User can enter or choose a date from a date picker.
Image of date field
dropdown
User can choose from a drop-down menu.
Image of drop down field
dropdownQuery
User can enter text in the search field and also specify the operator to use in the query. For example, you can add a drop down query to include options such as Is, Contains, and Starts with.
Image of drop down query field
nodePicker
User can select from a list of nodes.
Image of node picker field
number
User can enter numbers in the search field.
Image of number input field
radio
User can choose only one out of multiple options. You can also leverage the orientation attribute to determine whether to display the buttons horizontally or vertically.
Image of radio input field
text
User can enter text in the search field.
Image of text input field
toggle
User can toggle between two modes.
Image of toggle input field
orientation
Only used for the orientation of radio types. You can set the attribute to one of the following values:
  • horizontal
  • vertical.
The default value is horizontal.
value
The default display value.
list
A static list of values to display for drop-down menus and radio buttons.
fetch
Similar to a list but the display values are fetched by using IBM® Sterling Order Management System APIs. For information about the APIs, see Generating and accessing Javadoc.
Fetch is available for dropdown, dropdownQuery, and radio types only.
Optional: Within fetch, a translation attribute specifies any translation to apply to elements and attributes of the generated list.
  • key specifies which attribute in each element of the list to translate
  • prefix specifies a possible prefix to apply to the value of the attribute to determine the translation-key
For example, the following sample retrieves the translated strings by looking at the key my.prefix_<value-of-label-attribute>
"translation": { "prefix": "my.prefix_", "key": "label" }
operator
The operator to apply to the value that is specified in the API request invoked. You can set the attribute to one of the following values.
  • EQ - Equal to
  • LIKE - Contains
  • FLIKE - Starts with
target
Controls where the resulting value of the field can be applied.
To apply for all search queries, specify all.
Otherwise, you can explicitly set the attribute to one of the following values:
For order search pages
orders
The value is applied to searches where the Search for option in the UI is set to Order. In this case, ensure that the request attribute defines an input property from the getOrderList API.
alerts
The value is applied to alerts search in the search results tab. In this case, ensure that the request attribute defines an input property from the orders API.
releases
The value is applied to searches where the Search for option in the UI is set to Order releases. In this case, ensure that the request attribute defines an input property from the getOrderReleaseList API.
lines
The value is applied to searches where the Search for option in the UI is set to Order lines. In this case, ensure that the request attribute defines an input property from the getOrderLineList API.
receipts
The value is applied to searches where the Search for option in the UI is set to receipts. In this case, ensure that the request attribute defines an input property from the getOrderReceiptList API.
For shipment search pages
shipments
The value is applied to searches where the Search for option in the UI is set to Shipment. In this case, ensure that the request attribute defines an input property from the getShipmentList API.
shipment-containers
The value is applied to searches where the Search for option in the UI is set to Shipment container. In this case, ensure that the request attribute defines an input property from the getShipmentContainerList API.
request
When target is satisfied, the property (in dot-notation) to set in the API request invoked with the value of the field.
For information about the APIs, see Generating and accessing Javadoc.

JSON example

The following example provides some use cases for customizing the Order search and Shipment search pages.
Note: The following example includes inline comments as a guide to explain the attributes while you analyze the code. Since JSON does not support comments, this is not a valid JSON sample as displayed. If you plan to copy this sample, ensure that you remove the inline comments. 
{
  "orders": {
    "fields": [
      {	// 1  Example for standard text input
        "label": "Order name",	//The label to display in the user interface
        "type": "text",			//The type of field set to text 
        "request": "OrderName",	//Pass the user input to the specified property of the getOrderList API call
        "target": "orders",		//Value is used only on "Search for: orders"
      },	
      {	// 2  Example for node picker
        "label": "Shipping node",	
        "type": "nodePicker",
        "target": "releases",   //Value is used only on "Search for: Order release". 
        "request": "OrderLine.ShipNode",  //Pass the user selection to the specified getOrderReleaseList property
        "value": {
          "selectedNode": [],
          "enterprise": ""
        }
      },	  
      {	// 3  Example for dropdown that fetches payment method options from api
        "label": "Payment type",
        "type": "dropdown",
        "target": "orders",
        "request": "PaymentMethod.PaymentType",	//Pass the user selected value to the specified getOrderList property
        "fetch": {			//Identify that the dropdown options need to be fetched
          "api": "getPaymentTypeList",	//Fetch dropdown options from getPaymentTypeList api
          "type": "oms",				//Must be "oms" to fetch from Sterling Order Management API.
          "parameters": {				//Parameters to pass to getPaymentTypeList call
            "CallingOrganizationCode": "{{enterprise}}"
          },
          "response": {					//Get the response from getPaymentTypeList call
            "listAttribute": "PaymentType",		//Retrieve the 'PaymentType' from the response 
            "map": {
              "id": "PaymentType",		 //Sets the id to the values of the PaymentType response
              "label": "PaymentTypeDescription" //Sets the dropdown options to the values of the PaymentTypeDescription response
            }
          }
        }
      },	  
      {	// 4  Example for dropdown with static, user defined options 
        "label": "Is Pre Order",
        "type": "dropdown",
        "target": "orders",
        "list": [ { "id": "Y", "label": "Y" }, { "id": "N", "label": "N" } ],	//List the options of the dropdown
        "request": "OrderLine.CustomAttributes.BUC_IsPreOrder",				//Pass the user selected value to the specified property
      },
      {	// 5  Another example for dropdown with static, user defined options
        "label": "Is VIP Order",
        "type": "dropdown",
        "target": "orders",
        "request": "OrderLine.CustomAttributes.BUC_IsVIPOrder",
        "list": [ { "id": "Y", "label": "Y" }, { "id": "N", "label": "N" } ]
      },
      {	// 6  Example for dropdownQuery, which is text input along with operator choice of "Is", "Starts with", "Contains"
        "label": "Serial No",
        "type": "dropdownQuery",
        "target": "orders",
        "request": "OrderLine.SerialNo",
        "operator": "LIKE",		//Set the default to LIKE. LIKE == Contains, EQ == Is, FLIKE == Starts with
        "fetch": {
          "api": "getQueryTypeList",	//Call getQueryTypeList to get the list of options
          "type": "oms",				//Must be "oms" to fetch from Sterling Order Management API.
          "parameters": {},
          "translation": {
            "prefix": "ORDER_SEARCH.GENERAL.LABEL_QUERY_",	//To support translation, specify the key that holds the translated string. 
            "key": "label"				//The translations for "Is,Contains,Starts with" is provided by IBM.
          },						//For custom strings, you can add translated strings into the /assets/i18n folder
          "response": {				//Retrieve response from the getQueryTypeList call
            "listAttribute": "StringQueryTypes.QueryType",
            "map": {
              "id": "QueryType",
              "label": "QueryTypeDesc"
            }
          }
        }
      },	
      {	// 7  Example for toggle 
        "label": "Draft order",
        "type": "toggle",
        "target": "orders",
        "request": "DraftOrderFlag",	//Pass the user selected value to the specified property
        "list": [ 		//List options are based on the valid inputs for the property. In this case, DraftOrderFlag is a 1 character flag that requires the value Y or N
		{ "id": "true", "label": "Y" }, { "id": "false", "label": "N", "selected": "true" } 
		]
      },
      {	// 8  Example for radio type
        "label": "Kit code",
        "type": "radio",
        "list": [ 	//The list of radio options
		{ "id": "LK", "label": "Logical kit" }, { "id": "BUNDLE", "label": "Bundle" }, { "id": "", "label": "None", "selected": "true" } 
		],
        "target": "orders",
        "orientation": "vertical",		//Set orientation as vertical
        "request": "OrderLine.KitCode"	//Pass the user selected value to the specified property
      },	  
      {	// 9  Example for date 
        "label": "Import license expire date",
        "type": "date",
        "target": "orders",
        "request": "OrderLine.ImportLicenseExpDate" //Pass the user selected value to the specified property
      },	  
      {	// 10  Another example for text 
        "label": "Customer zip code",
        "type": "text",
        "request": "CustomerZipCode",
        "target": "orders",
      },
      {	// 11  Example for dropdown that fetches unit of measure options from api
        "label": "Custom unit of measure",
        "type": "dropdown",
        "target": "orders",
        "request": "MeasureOfUnit",	//Pass the user selected value to the specified getOrderList property
        "fetch": {					//Identify that the dropdown options need to be fetched
          "api": "getItemUOMMasterList",	//Fetch dropdown options from getItemUOMMasterList api
          "type": "oms",			//Must be "oms" to fetch from Sterling Order Management API.
          "parameters": {			//Parameters to pass to getItemUOMMasterList
            "CallingOrganizationCode": "{{enterprise}}",
            "UOMType": "QUANTITY",
            "IsInventoryUOM": "Y"
          },
          "response": {		//Get the response from getItemUOMMasterList call.
            "listAttribute": "ItemUOMMaster",	//Retrieve the 'ItemUOMMaster' from the response 
            "map": {
              "id": "UnitOfMeasure",	//Sets the id to the values of the PaymentType response
              "label": "Description"	//Sets the dropdown options to the values of the ItemUOMMaster.Description response
            }
          }
        }
      },
	  {	// 12  Another example of node picker 
        "label": "Merge node",
        "type": "nodePicker",
        "target": "orders",            //Applies only to "Search for: Order" 
        "request": "OrderLine.MergeNode",  
        "value": {
          "selectedNode": [],
          "enterprise": ""
        }
      },
      {    //Example for addressPicker
        "label": "Payment bill to",
        "type": "addressPicker",
        "target": "orders",
        "request": "PaymentMethod.BillToKey",  //Pass the user value to the specified getOrderLineList property
        "value": {
          "content": "",
          "address": ""
        }
      },
      {
        "label": "Prime line number",
        "type": "number",
        "request": "PrimeLineNo",    //Pass the user value to the specified getOrderLineList property
        "target": "all",             

      },
      {
        "label": "Batch No",
        "type": "dropdownQuery",
        "target": "orders",                //Apply to Search for: Orders
        "request": "OrderLine.OrderLineInvAttRequest.BatchNo",
        "operator": "LIKE",
        "fetch": {
          "api": "getQueryTypeList",
          "type": "oms",
          "parameters": {},
          "translation": {
            "prefix": "ORDER_SEARCH.GENERAL.LABEL_QUERY_",
            "key": "label"
          },
          "response": {
            "listAttribute": "StringQueryTypes.QueryType",
            "map": {
              "id": "QueryType",
              "label": "QueryTypeDesc"
            }
          }
        }
      },
      {
        "label": "Is open receipt",
        "type": "toggle",
        "target": "all",
        "request": "OpenReceiptFlag",
        "list": [ { "id": "true", "label": "Y" }, { "id": "false", "label": "N", "selected": "true" } ]
      },
      {
        "label": "Lot Attribute 1",
        "type": "dropdownQuery",
        "target": "orders",
        "request": "OrderLine.OrderLineInvAttRequest.LotAttribute1",
        "operator": "LIKE",
        "fetch": {
          "api": "getQueryTypeList",
          "type": "oms",
          "parameters": {},
          "translation": {
            "prefix": "ORDER_SEARCH.GENERAL.LABEL_QUERY_",
            "key": "label"
          },
          "response": {
            "listAttribute": "StringQueryTypes.QueryType",
            "map": {
              "id": "QueryType",
              "label": "QueryTypeDesc"
            }
          }
        }
      }
    ]
  },
  "shipments": {   //object for shipment search page
    "fields": [
        { 
            "label": "Freight terms",
            "type": "dropdown",
            "target": "shipments",   //Applies only to "Search for: Shipment" 
            "request": "FreightTerms",    //Pass the user selected value to the specified getShipmentList property
            "fetch": {                //Fetch dropdown options from getFreightTermsList API
                "api": "getFreightTermsList",    
                "type": "oms",        //Must be "oms" to fetch from Sterling Order Management API.
                "parameters": {
                    "CallingOrganizationCode": "{{enterprise}}"
                },
                "response": {
                    "listAttribute": "FreightTerms",   //Retrieve the FreightTerms property from the response
                    "map": {
                        "id": "FreightTerms",          //Assign IDs to the options
                        "label": "Description"         //Sets the dropdown options to the values of the Description response
                    }
                }
            }
        },
        {
            "label": "Ship via",
            "type": "dropdown",
            "list": [ { "id": "ROAD", "label": "Road" }, { "id": "AIR", "label": "Air" }, { "id": "SEA", "label": "Sea" } ],
            "target": "shipments",
            "request": "ShipVia"
        },
        {
            "label": "Quantity",
            "type": "number",
            "target": "shipments",
            "request": "ShipmentLines.ShipmentLine.Quantity"
        },
        {
            "label": "Backroom pick complete",
            "type": "dropdown",
            "list": [ { "id": "Y", "label": "Y" }, { "id": "N", "label": "N" } ],
            "target": "shipments",
            "request": "ShipmentLines.ShipmentLine.BackroomPickComplete"
        }
    ]
  }
}

User interface example

The following image illustrates the Order outbound search page after uploading the JSON example to IBM.
Screen shot displaying the Order outbound user interface with search for order release and search by item filters selected.