API Documentation
      Back to home
      1. Knowledge Base
      2. Modules & Features
      3. API Documentation

      How to Work with Custom Fields in the Infoplus API

      Utilize custom fields to input any data into an API call, which will import that data into any desired Infoplus table.

      Custom Fields in Infoplus allow users to add additional data to any table in Infoplus.  These fields can be viewed and edited when viewing tables or individual records and they can be used to search for records through the Infoplus UI. 


      This is an especially powerful feature for API users, as you can add data from your external system to Infoplus which may not otherwise fit within Infoplus.  


      Here's an overview of how Custom Fields work in Infoplus:  

      • Infoplus supports 5 different data types for custom fields:  
        • String (max length 250)
        • Integer
        • Decimal
        • Boolean
        • Date
      • You can have up to 20 different custom fields of each data type on each table in Infoplus. For example, on the Items table, one might use 19 Strings, 8 Integers, 3 Booleans and a Decimal.  Then on the Orders table maybe 12 Strings, 15 Integers, and 2 Dates. 
      • Custom fields are the same across all of your Lines of Business within Infoplus (that is to say, if you have 2 LOB's, they would both have the same fields available on each table).

      Custom Fields can be fully managed through the Infoplus API.  Every API data type which is exposed as a Table within Infoplus has a customFields object available under it in the API.  This object has keys corresponding to the names of each custom field that your site has set up on that table.  


      For example, if your client has a custom field called "priority", and another called "nickname" on the Warehouse Zone table, then an API model object from the zone endpoint may look like this:  

      {
         "id": 7,
         "name": "Down Forward",
         "customFields":
         {
            "priority": 1,
            "nickname": "Forward"
         },
         ...
      }

         

      How to Insert a Record with Custom Fields

      When inserting a record, you can include the customFields object under the JSON object that you POST, and the values specified will be stored along with the new record that is inserted.  


      For example, this HTTP request: 

      POST /infoplus-wms/api/beta/zone

      With this payload:

      {
         "name":  "Back Storage",
         "customFields":
         {
            "priority": 10,
            "nickname": "Back"
         }
      }

      Would insert a row in the Zone table, with both of its custom fields set

      To insert a value through a Script using the API:

      order.customFields.put("customFieldName", customFieldData);

      How to Update Custom Fields for a Record

      To update values in custom fields, you must issue a PUT request to the updateCustom endpoint under the data type that you are trying to update.  For the Zone example above, this endpoint may look like (depending on your version) beta/zone/updateCustom 


      The object that you PUT to this endpoint must contain, at a minimum, the primary key from the record being updated, along with the customFields object, containing any custom field values that you wish to update.  Any custom fields which are excluded from the object will NOT be updated.  Also, no values in the main entity will be updated.  The only values updated in Infoplus will be the fields specified under your customFields object.  


      For example, this HTTP request:

      PUT /infoplus-wms/api/beta/zone/customFields

      With this payload:

      {
         "id": 7,
         "customFields": { "priority": 1 }
      }

       Would update only the "priority" custom field on the Zone with id=7.


      To update a value through a Script using the API (same as an insert):

      order.customFields.put("customFieldName", customFieldData);

      To update just the custom field values on a record, you can use updateCustomFields: 

      infoplusApi.updateCustomFields("fieldName", record); 


      How to Search by Custom Fields

      To search for records in the Infoplus API based on values in custom fields, you can specify your custom fields in the filter query string parameter using the notation of "custom." plus your custom field's name.  For the Zone example from above, to find all Zones with a priority less than 5, you would use a filter parameter of:  custom.priority lt 5.  


      For example:

      GET /infoplus-wms/api/beta/zone/search?filter=custom.priority lt 5

      To get a value through a Script using the API:

      order.customFields.get("customFieldName");

      Another way to search is to build a script like this to use the API:

      var exampleVariable = infoplusApi.search("order", "custom.customField eq 
      'shipToZip'", null, 1, "name");

      Real World Use Case Examples

      Use Case:

      You have extra data in your Order on the Order Line level that needs to be captured per line item but whenever you try to update the Order via the API, you receive an error that the Order Line fields are not editable.

      Error:
      Wrapped com.materialogic.core.exceptions.UserFacingException: extendedDeclaredValueOverride is not editable

      Solution: 

      • Create a Custom Field on the Order Line table
      • Create a trigger on the Order table to call a script during Insert
      • Use a script like the one below, which takes the Order Id and inserts it into Custom Field, to push the correct information into the Order Line

      Use Case:

      Add a surcharge for a client via the shipment table. Learn how here.