3Entity Module

Supported Entities

The lgfapi entity module is used to access and modify OCWMS application data. It exposes specific methodologies for identifying subsets of data and obtaining their representations as well as allowing for the creation of certain resources. The entities supported and corresponding functionality will continue to be expanded through subsequent releases.

The entity module has a documenting feature that can be accessed via a GET request to the top-level (root) URL (…/ lgfapi/v10/entity/). This will return a sorted list of supported entities for the given lgfapi version and an accompanying base URL.

Each entity represents an object or combination of objects within OCWMS that is accessible via lgfapi. However, not all entities support all HTTP methods. Furthermore, these entities may share characteristics with their respective counterparts in other areas of the OCWMS application, but as a whole should be considered independent of other application functionality.

Entity Metadata

It is possible to obtain additional information for each entity by making a GET request to the “describe” entity operation (…/lgfapi/v10/entity/{entity_name}/describe/). This will return metadata that can be used to further your understanding of the entity. See “Entity Operations” section for more details.

Input Data Types

Lgfapi supports user input depending on the HTTP method:

• GET/HEAD
  • Query string parameters
• POST
  • Request body data
    • The format must be JSON or XML
  • The “format” query sting parameter alone is supported to specify the desired format for the response.

Although the input formats may be type ambiguous, the input value is cast to the appropriate type as defined in the entity’s field metadata. Some fields have naming conventions that are outlined below. The following types are supported for user input:

String/Text

Query String: …/?field=abc123

JSON: {“field”: “abc123”}

XML: <field>abc1234</field>

Integer

Query String: …/?field=123

JSON: {“field”: 123}

XML: <field>123</field>

Numeric/Decimal

Query String: …/?field=1.234

JSON: {“field”: "1.234"}

XML: <field>1.234</field>

Special Note about JSON Decimal Values

When sending decimal values in a JSON request, it is recommended to send them wrapped in double quotes like a string value, as seen in the example above. This will prevent against any loss of precision as part of the lgfapi request.

Boolean

Except for a few specific cases, all True/False Boolean field names end with “_flg”.

The input value for all formats should be either “true” or “false”.

Query String: …/?field_flg=true

JSON: {“field_flg”: true}

XML: <field_flg>true</field_flg>

Temporal (Date/Time)

All date, time, and date-time fields require the iso-8601 format: YYYY-mm-ddTHH:MM:SS.ffffff

Note that the microsecond component “f” is optional. Using January 30th, 2018 at 6:30pm as an example:

Date

Field names for date-only fields typically end with “_date”.

Query String: …/?field_date=2018-01-30

JSON: {“field_date”: “2018-01-30”}

XML: <field_date>2018-01-30</field_date>

Time

Field names for time-only fields typically end with “_time”.

Query String: …/?field_time=18:30:00

JSON: {“field_time”: “18:30:00”}

XML: <field_time>18:30:00</field_time>

Date-time

Field names for date-time fields typically end with “_ts”.

All Date-time objects are assumed to be in the time zone of the user’s facility context. In other words, it should be the date/time you would expect to see if viewed by the user in the UI.

Query String: …/?field_ts=2018-01-30T18:30:00

JSON: {“field_ts”: “2018-01-3030T18:30:00”}}

XML: <field_ts>2018-01-3030T18:30:00</field_ts>

Date/Time Values and Time Zones

Note: Field names for date-time fields typically end with “_ts”.

It is a recommended best practice to always pass time zone aware date-time values that include the time zone offset component so that there is no ambiguity. The following examples show the time zone specified as UTC (+00:00):

• Query String: field_ts=2018-01-30T18:30:00+00:00
• JSON: {“field_ts”: “2018-01-3030T18:30:00+00:00”}
• XML: <field_ts>2018-01-3030T18:30:00+00:00</field_ts>

However, if a time zone naive date-time value is received by lgfapi, it is assumed to be in the time zone of the user’s default facility. In other words, it would be the date/time you expect to see if viewed by the user in the UI for their default facility.

• Query String: field_ts=2018-01-30T18:30:00
• JSON: {“field_ts”: “2018-01-3030T18:30:00”}
• XML: <field_ts>2018-01-3030T18:30:00</field_ts>

Relational

Relational fields are when one resource has a link to another resource. These fields always end in “_id” and by default, are integer values. They are unique when filtering, in that you can use the double-underscore (“__”) notation to reference a related resource’s fields, or even nested related resources. This is covered in more detail in the Resource Result Set Filtering section.

Query String: …/?field_id=1

JSON: {“field_id”: 1}

XML: <field_id>1</field_id>

Resource Result Set Filtering

Lgfapi offers the ability to apply filters to GET and HEAD requests in order to narrow down the final result set. This is done by adding query string filter parameters to the URI. Furthermore, lgfapi supports several built-in lookup functions to assist in common filtering tasks.

It is important to note that all entity data is automatically filtered by the user’s eligible facilities and companies. This prevents users from being able to access and/or change data outside of their assigned scope that same way that data is isolated in the UI or RF features. The difference with lgfapi is that users may access data from multiple eligible facilities and companies in a single request. In the UI and RF, this typically requires manually changing the user’s context.

The most basic format for a filter uses simply the exact operator (“=”): …/?field=value

This can be chained to apply multiple filters: …/?field1=value1&field2=value2

Lgfapi uses double underscore (“__”) notation in order to join multiple fields or functions in the query string filters. The double underscore is used to distinguish the field names when filtering on a related resource’s attributes or when applying a lookup function.

Applying a lookup function: …/?field__lookup=value

Filtering on a related resource: …/?relation_id__related_field=value

Applying a lookup function on a related resource: …/?relation_id__related_field__lookup=value

Supported Lookup Functions

The following lookup functions are provided by lgfapi. Note that any match function with a corresponding “i” function means that function is case-insensitive. For example, “exact” is used to match exactly on a value, as does “iexact” except that the latter ignores upper/lower case.

Arithmetic Lookups

gt – Greater than

Example: Filtering sales order detail(s) for only those with an ordered quantity.

…/order_dtl/?ord_qty__gt=0

• gte – Greater than or equal to

Example: Filtering sales order detail(s) for only those with an ordered quantity.

…/order_dtl/?ord_qty__gte=1

• lt – Less than

Example: Filtering sales order detail(s) for only those with ordered quantity below 10.

…/order_dtl/?ord_qty__lt=10

• lte – Less than or equal to

Example: Filtering sales order detail(s) for those with ordered quantity at or below 10.

…/order_dtl/?ord_qty__lte=10

Text Match Lookups

• contains/icontains – Text contains substring

Example: Filtering sales order(s) for orders with “FOO” in the order_nbr field.

…/order_hdr/?order_nbr__contains=FOO

Example: Same as previous example, but ignore case.

…/order_hdr/?order_nbr__icontains=FOO

• exact/iexact – Text exactly matches

Example: Match sales order(s) exactly on the order number.

…/order_hdr/?order_nbr__exact=ORDER001

Note: “Exact” is not typically needed. The above filter condition does not require the exact lookup since this is automatically implied by the exact operator (“=”).

The query string can be simplified to:

…/order_hdr/?order_nbr=ORDER001

“iexact”, on the other hand, is a useful tool when you need to do an exact match, but ignore letter casing:

…/order_hdr/?order_nbr__iexact=OrDeR001

• startwith/istartswith – Text starts with

Example: Filtering sales order(s) for only those whose order_nbr starts with “ORD”:

…/order_hdr/?order_nbr__startswith=ORD

• endswith/iendswith – Text ends with

Example: Filtering sales order(s) for only those whose order_nbr ends with “001”:

…/order_hdr/?order_nbr__endswith=001

Temporal (Date/Time) Lookups

The following temporal functions may only be used on date, time, and/or date-time data. Consider the “order_hdr” entity’s “order_shipped_ts” date-time field with a value “2018-09-17T20:30:59”:

• year – Match on a date’s year (date or date-time).

…/order_hdr/?order_shipped_ts__year=2018

• month – Match on a date’s month (date or date-time).

…/order_hdr/?order_shipped_ts__month=09

• week_day – Match on a date’s day of the week (date or date-time).

Takes an integer value representing the day of week from 1 (Sunday) to 7 (Saturday).

…/order_hdr/?order_shipped_ts__week_day=2

• day – Match on a date’s day (date or date-time).

…/order_hdr/?order_shipped_ts__day=17

• hour – Match on a date’s hour (time or date-time).

Assumes a 24-hour clock.

…/order_hdr/?order_shipped_ts__hour=20

• minute – Match on the time’s minutes (time or date-time).

…/order_hdr/?order_shipped_ts__minute=30

You can also apply other lookup and arithmetic functions to temporal fields:

• Date Range

For example, if we have a date-time field where we want to search for resources that have a value within a range, it is possible to chain two temporal filters together to search within a set date range:

…/order_hdr/?order_shipped_ts__gte=2018-09-01T00:00:00&order_shipped_ts__lt=2018-10-01T00:00:00

Or, it is possible to use the “range” lookup function:

…/order_hdr/?order_shipped_ts__range=2018-09-01T00:00:00,2018-10-01T00:00:00

However, since in this example we don’t have any specific time data, this could have also been accomplished more easily using the “month” lookup:

…/order_hdr/?order_shipped_ts__month=09

There may be multiple different ways to arrive at the same result when filtering. It is always desirable to be as specific as possible to minimize the result set and improve efficiency.

Additional Lookups

• isnull – Boolean; Is the field’s value null?

This lookup is used to test if a field is null. This is a useful lookup as it can be used on any type of field to test for null.

Example: Filtering sales order(s) for only those where the shipped timestamp is null:

…/order_hdr/?order_shipped_ts__isnull=true

This is important because it allows you to make this test for any field type. If, for example, you tried to filter on the field’s value directly (…/order_hdr/?order_shipped_ts=null), you would receive an error that “null” is not a valid date. Since the field is of type date-time, it is expecting a temporal value and is interpreting “null” as the input.

• in – Filter by values in a list

This lookup function allows for filtering by a group of values. These values may be a mix of different types, but the type(s) should be consistent with the type of the field being filtered. The input is a comma-delimited list with no spaces between entries in the list.

Example: Filter order_hdr by specific status id values:

…/order_hdr/?status_id__in=10,30,90

Or, it can be applied for filtering on a specific set of sales order numbers:

…/order_hdr/?order_nbr__in=ORDER001,ORDER002,ORDER003

It is also possible to use an “in” lookup with a single value to effectively function the same as an exact operator (“=”). The two following examples are equivalent in that they will return the same result set:

…/order_hdr/?order_nbr=ORDER001

…/order_hdr/?order_nbr__in=ORDER001

The difference is that an “in” lookup in inherently slower because of the way the filter is built and applied when filtering the data. If you have a single value to match on, it is recommended to use “=” instead of “in”.

• range – Filter for resources with value within an inclusive range.

Numeric range

…/order_hdr/?status_id__range=10,90

Date range

…/order_hdr/?order_shipped_ts__range=2018-09-01T00:00:00,2018-10-01T00:00:00

Relational Resource Filtering

It is possible to filter on any related field for the given entity. All related field names end with “_id” and are integers by default.

For example, the simplest and fastest performing related resource filter is to search directly on the resource’s id. An “id” is the unique value assigned to every resource. Using the “order_hdr” field, “facility_id”, we could filter specifically for order belong to the facility with id “1”:

…/order_hdr/?facility_id=1

Adding the “company_id” field is a very common thing to do, in order to filter resources by facility and company (assuming the company’s id is also “1”):

…/order_hdr/?facility_id=1&company_id=1

But what if we wanted to filter by the value of a field belonging to the related resource. For example, what if we knew the facility and company codes, but didn’t yet know their respective “id” values. It is possible to filter on the related resource’s fields using double-underscore (“__”) notation.

Assuming facility with id=1 has a code “FAC1” and company with id=1 has a code “COM1”:

…/order_hdr/?facility_id__code=FAC1&company_id_code=COM1

This is not as efficient as using just the “id” of the related resources since lgfapi will need to do an additional lookup for each related resource to filter on their respective “code” fields. It is recommended to cache client-side the “id” values of commonly used, static entities (like facility and company) in order to improve performance in high-throughput systems.

It is also possible to filter multiple levels deep with related resources. For example, in order to filter on the order’s facility’s parent company, we could further chain the facility field, “parent_company_id”, as it is a related resource of “facility_id” and of entity type “company”:

…/order_hdr/?facility_id__parent_company_id=1

Again, you can also search on a related field:

…/order_hdr/?facility_id__parent_company_id_code=COM1

This is a handy and powerful tool for looking up resource sets based on related data. However, it is important to remember that as the relational filter depth increases, the performance may decrease as well since there is more work to be done to lookup related resource(s). Client-side caching and other performance methodologies are discussed in their own section.

Chaining Multiple Filters

It is possible to chain multiple filters on the same field. Each condition is just another key-value pair where the field is consistent. For example, if we wanted to filter the order_hdr entity to return those whose order_nbr starts with “ABC” and additionally contains the word “TEST”, we would write it as:

…/order_hdr/?order_nbr__startswith=ABC&order_nbr__contains=TEST

It is possible to chain together any number of different field and lookup combinations to arrive at your desired result set. However, it is important to note that the more filters applied, the more the performance may degrade. Therefore, it is always preferred to be as specific as possible when using filtering.

Resource Representations (GET)

Within the lgfapi entity module, JSON or XML resource representation(s) of entity(s) may be obtained through a GET request. A GET request is made for a specific entity in the format:

…/lgfapi/v10/entity/{entity_name}/

By default, each request is filtered by the requesting user’s eligible facility(s) and company(s). It is possible to add additional filter conditions in the URI query string in order to arrive at the data required. If, after filtering, no data is found, a 404 – Not Found error will be returned in the standard lgfapi response.

Furthermore, there are two conventions for how to request resource representation(s) – “list” and “retrieve”. For the following examples, the “company” entity will be used.

List

A list request is used to fetch one or more object representations of an entity. The result set is based on the default facility/company context filters and any optional filter parameters provided in the URI. The default results set is comprised of all resources for the given entity that are eligible to the requesting user. Since the result set may be of an arbitrarily size, a paginated data set is always returned.

The representation for all eligible objects can be requested by not providing the query string portion of the URI:

…/lgfapi/v10/company/

Query string filter parameters may optionally be used to further narrow down the data set. For example, to filter additionally by company code “ABC”, we would add the following:

…/lgfapi/v10/company/?code=ABC

Retrieve

A retrieve request is used to fetch a single resource by its integer “id” value. This is the most performant way to get a representation for a single resource where the “id” is known. The result set is not paginated. The “id” value is specified in the URI after the entity name:

…/lgfapi/v10/company/{id}/

For example, if we had previously looked up the company with code “ABC” and found its “id” value to be 1, we could retrieve its representation in the future by making a GET request to the URI:

…/lgfapi/v10/company/1/

Note that since the lookup is for a specific resource, no filters are allowed in the query string. It is permitted to pass in allowed non-filter reserved parameters like “format” and “fields”. However, any pagination related query string parameters like “page_mode” are not supported since the returned representation is not paginated.

Note: …/lgfapi/v10/company/?id=1 is still considered a “list” style request and is paginated.

Last-Modified HTTP Header

If the requested resource exists and the data is temporally tracked, the Last-Modified HTTP header will be returned. This is the date-time that the resource was last updated. It is in iso-8601 format in the requesting user’s time zone. This can be cached client-side and used in conjunction with HEAD requests as an efficient way to check for resource modification.

Resource Representation Data Conventions

For both list and retrieve GET requests, the “format” query string parameter can be passed in order to convey the desired response format as “json” (default) or “xml”.

Hyperlink-Related Resource Representations

All resources use hyperlinked representations for related resource fields. These are the fields whose name ends with “_id”. They represent another entity resource that can generate its own representation using the hyperlink provided. Lgfapi uses hyperlinked relationships to allow for users to crawl to the intended data sets. This allows for the preservation of RESTful principals as well as to keep the data interchange sizes manageable.

All related field representations contain three pieces of information:

1. “id” – The integer id value of the related resource
2. “key” – A string identifier for the related resource
3. “url” – A crawl-able retrieve style hyperlink to the related resource
   • Both “id” and “key” are always provided. However, the value for “url” may be blank if the related resource it not one of the supported entities. In this case, it is not possible to build a hyperlink to the resource as it does not support generating its own representations.

For example, when getting a representation for the “company” entity where the company is of type Regular, the related field “company_type_id” would be represented like the following JSON string:

{

…

“company_type_id”: {

“id”: 1,

“key”: “R”,

“url”: “https://…/wms/lgfapi/v10/entity/company_type/1”

},

…

}

Or, if the desired format is XML:

<company>

…

<company_type_id>

<id>1</id>

<key>R</key>

<url>https://.../wms/lgfapi/v10/entity/company_type/1</url>

</company_type_id>

…

</company>

The only exception for the related field representation format is for status_id related fields. These fields are always represented as only the related resource’s integer “id” value. It is possible to get a representation for any status-based entity by making a retrieve request. The only difference is that due to the volume of status fields on various entities, the integer value is used to reduce payload size.

For example, the “order_hdr” entity has the related field “status_id” for the entity “order_status”. It is represented on the “order_hdr” as just the “id” value:

{

…

“status_id”: 10,

…

}

However, it is possible to get a representation of the status by making the request:

GET https://.../wms/lgfapi/v10/order_status/10

Important

There are many related resource fields that are optional. If there is no linked resource, the field’s value will be “null” if using JSON or an empty tag if using XML. For more information, reference the entity’s field metadata for the “required” attribute.

Related Data Sets

The related resources previously discussed all link to a single resource. However, it is possible that the current resource has a list many other linked resources of the same type. A good example is a sales order header that has one or more child details. As a convenience and additionally for guidance/performance reasons, many entity representations have additional hyperlinked relations to these data sets. These field names always end in “_set”.

Continuing the sales order header example, the order details set could be represented as the following in an order_hdr retrieve representation. Assume there are two detail line items and the “id” value of the order_hdr entity is “123”.

GET https://.../wms/lgfapi/v10/entity/order_hdr/123

{

“id”: 123,

…

"order_dtl_set": {

"result_count": 2,

"url": "https://.../wms/lgfapi/v10/entity/order_dtl/?order_id=123"

},

…

}

It’s important to note that unlike the “_id” related resources which have a retrieve style hyperlink to the specific resource, “_set” related representations use list style with query string filters in order to return a paginated list of 1 to n resource representations. Also, instead of giving the “id” and “key”, the related count is returned.

If no related resources are found for the set, the value will be “null” for JSON representations and an empty tag for XML.

Field Selection

GET requests for the lgfapi entities support the “fields” query string parameters. It takes a comma-delimited list of field names for the entity and returns only those fields in the representation.

For example, to return only the “id” and “code” for all eligible companies using a list style request with no filters:

GET https://.../wms/lgfapi/v10/entity/company?fields=id,code

The “fields” parameter can be combined with filter parameters and other parameters with special meaning, like “format”. Here is a more complex example if one wanted to search for all eligible companies of type regular and return only the “id” and “company” for each company entity found, in XML format:

GET https://.../wms/lgfapi/v10/entity/company?fields=id,code&format=xml&company_type_id=1

This can also be applied to retrieve style request for a specific resource:

GET https://.../wms/lgfapi/v10/entity/company/1?fields=id,code

This is an important tool when performance is of concern. If it is known ahead of time that only specific field values are required, narrowing the returned data set using the “fields” parameter can greatly reduce the overall payload size and remove the need for unnecessary field and/or relation lookups.

Ordering

By default, no ordering is applied to list style GET requests that can return 0 or more representations. This is done for performance considerations as applying ordering to any request may degrade performance, especially in the case of larger data sets.

It is possible to specify an order-by clause for list style requests using the “ordering” query string parameter. It accepts a comma-delimited list of field names by ordering priority.

For example, one could request all eligible companies and order by the type and then the code:

GET https://.../wms/lgfapi/v10/entity/company/?ordering=company_type_id,code

By default, fields are ordering ascending. To order by descending value, add a dash (“-“) before the field name in the ordering list. This can be applied to order first by company type ascending and then company code descending:

GET https://.../wms/lgfapi/v10/entity/company/?ordering=company_type_id,-code

Just like any other query string parameter, it may be chained with other parameters and filters.

Resource Existence and Modification (HEAD)

HTTP requests for lgfapi entities using the HEAD method are an efficient way to determine if a resource or list of resource(s) exists. Additionally, it is possible to determine if a specific resource has been modified since a target date-time. The HEAD method does not return any data in the body of the response. The only data returned is the response status code and any HTTP headers. Because HEAD requests do not have to know specifics about each resource and build a representation (like in a GET request), minimum data is transmitted and the server-side determinations can be optimized.

HEAD requests accept both retrieve and list style URI that same as a GET request. This can be used to check for the existence of a specific resource or filter for the existence of potentially many resources in a list.

“If-Modified-Since” HTTP Request Header

Entity HEAD requests allow for the requester to optionally pass the “If-Modified-Since” HTTP header in the request. This is only permitted for retrieve style requests when querying for a specific resource by id in the URL. The header’s value is the target date-time in iso-8601 format in the appropriate time zone. When provided, the value will be compared to the resource’s last modification time to determine if it has been modified since the header’s date-time. If the resource exists, and it has been modified, a 200 - Ok status code is returned. If it exists but has not been modified, a 304 – Not Modified status code is returned.

Not that if the entity does not support mod time tracking, the header is ignored and a 200 – Ok response code is returned meaning only that the resource exists.

The “If-Modified-Since” request header is typically used in conjunction with the “Last-Modified” response header that is returned with every retrieve style GET request for those entities that track mod timestamps. For example, a common scenario might start with a retrieve style GET request being made for a resource. The value of the “Last-Modified” response header is saved client-side for that resource. Sometime later, the client wants to check if the resource has been updated. A HEAD request can be made to determine if the resource has been modified since the original GET request by passing the last mod timestamp in the “If-Modified-Since” request header.

In scenarios where the updated resource representation is not needed, a HEAD request is much more efficient than a GET request. Or, it may be used to determine if a more expensive GET request is subsequently called to fetch the updated resource representation. It is also common to use HEAD request modification checks as a trigger mechanism for down-steam operations.

Response Statuses

The HTTP response status will be one of the following and vary depending on the outcome and if checking for existence or existence and modification of one or more resources. Note that this is not the full list of all possible response statuses. Rather, the following statuses are directly tied to this HTTP method’s functionality within lgfapi. For example, one can still receive a 401 status code if not providing valid user authentication credentials.

• 200 - Ok

When checking for only existence, a 200 status code response means that the resource(s) exist. When additionally checking for modification, this status code confirms that the specific resource exists and has been modified.

• 304 – Not Modified

Only applicable when checking for modification of a specific resource using the 'If-Modified-Since' header. This status means that the resource exists but has not been modified since the input target date-time.

• 400 - Bad Request

For HEAD requests, it is possible to receive this status when using the 'If-Modified-Since' header with an invalid date-time value or format. This may also be returned if other invalid data is found, such as invalid query sting filters.

• 404 - Not Found

No resource(s) were found based on the input provided. This may mean that either the resource(s) do not exist, or they do exist but the requesting user is not eligible for any of the resources.

For example, use a retrieve style request to check for the existence of a company entity with id=1:

HEAD https://.../wms/lgfapi/v10/entity/company/1

Or, it can be applied to a list style request with filters:

HEAD https://.../wms/lgfapi/v10/entity/company?code=ABC

Creating a Resource (POST)

Lgfapi allows for the creating and linking of a limited number of entity resources using an HTTP POST request. The new resource’s initial data set is passed in the body of the request, in the structure and formats outlined below. The requesting user must have the “lgfapi_create_access” permission. Also, the requesting user must be eligible for the facility/company context of the data being created.

Example request to create an IBLPN:

POST …/wms/lgfapi/v10/entity/iblpn/

Input Data

Data passed in the body of any POST request to the entity module requires the follow structure and data conventions.

Data Structure

Data is input in the request body in one of two sections:

• Fields – Initial field data. The “fields” section is used to pass in the initial field data required by the entity. Optional fields have a default and should be omitted from the “fields” data if you with the default to be applied. Lgfapi will attempt to use any data passed in the request body over the field default.
• Options – Additional/miscellaneous data. The “options” section is used to pass in extraneous data not directly required by the entity. A common example is the need to pass in a reason code when creating certain entities for the purposes of tracking against writing inventory history records.

JSON Example

{

“fields”: {

“string_field”: “ABC”,

“decimal_field”: 1.234

},

“options”: {

“reason_code: “RC”

},

}

XML Example

<request>

<fields>

<string_field>ABC</string_field>

<decimal_field>1.234</decimal_field>

</fields>

<options>

<reason_code>RC</reason_code>

</options>

</request>

Dates/Times

Temporal data must be iso-8601 format.

Related Resources

Relational fields (denoted by a field name ending in “_id”) require the integer “id” value of the target resource. This can be obtained by making a GET request to the corresponding entity with appropriate filters.

Assuming that you already know the corresponding fields each have an “id” value of 1; when creating a new resource with the required related fields “facility_id” and “company_id”, the JSON POST request body is modeled as:

{

“fields”: {

“facility_id”: 1,

“company_id”: 1

}

}

If a related field is optional and not required as part of the initial resource creation, the field should be omitted to apply the default value.

Response Statuses

A non-paginated representation of the new resource will be returned in the body of the HTTP response in the desired format.

200 – Ok

A lookup was done and it was determined that the resource already exists. No new resource was created. Instead, the body of the response contains a representation of the existing resource. This is only applicable to certain entities.

• 201 - Created

The resource was successfully created.

• 400 - Bad Request

The request was invalid. This could be due to data validation failures, permission errors, or other missing requirements of the operation.

Validations

Field and object-level validations are applied before the new resource is created. Any errors will be returned the response body in the standard format. All related resources must be within the facility/company context of the resource being created. Meaning, users cannot link the new resource to any resources outside of its facility and/or company. For example, it is not possible to link an IBLPN to a pallet where the pallet is for a different facility or company than the IBLPN.

Nested Related Objects

Some entities, such as “inventory”, allow for the creation and association of some related objects within the request to create the inventory object. This allows for the creation of multiple related objects using a single API call instead of multiple requests.

The currently supported related objects are “batch_number” and “inventory_attribute”. Instead of passing in the “id” value of the related objects as the field definition’s value, you may alternatively insert a nested object representation. If the nested object does not exist, it will be created. If it does exist, no creation for that object takes place but in both cases it will be associated to the inventory object being created.

For example, when making a POST request to create an inventory object, it is valid to associate an existing batch using its “id” value:

{

“batch_number_id”: 1,

…

}

It is also possible to send a nested representation of the batch object which will functionally act as “get or create”. The nested object must still pass all of the same validations as if it were being created independently and its “id” value passed in:

{

“batch_number_id”: {

“batch_nbr”: “BATCH001”,

“item_id”: 1,

“expiry_date”: “2019-01-01”

},

…

}

Supported Entities

• inventory_attribute
  • Functions as get-or-create based on the provided attributes for the given facility and company combination.
• batch_number
  • Function as get-or-create based on the batch number for the given facility and company combination.
• iblpn
  • Creates an inbound container with no inventory.
• inventory
  • Creates inventory in either an iblpn or an active location.
  • Requires “reason_code” option for inventory history tracking.
  • Success results in inventory history adjustment(s) being generated.
  • Supports nested “batch_number” and “inventory_attribute” object creation.
• inventory_lock

Create an inventory lock that can applied to containers and locations.

Updating a Resource (PATCH)

Lgfapi allows you to update specific fields on a limited number of entity resources using an HTTP PATCH request. Only the desired changes are to be passed in the body of the request using the “fields” section (very similar to a create resource (POST) request). The requesting user must have the “lgfapi_update_access” permission and must be eligible for the facility/company context of the data being modified. Successful modification will additionally update the object’s “mod_ts” and “mod_user” fields.

The entities and fields that may be modified are limited at this time, with a few exceptions, to custom (“cust”) fields, where supported. These fields are for “pass through” data that generally has no functional significance.

Updates are restricted to a single object per request and the “id” of the target object is required as part of the resource URL.

The following is an example URL to update a sales order:

PATCH …/wms/lgfapi/v10/entity/order_hdr/123/

Input Data

Data passed in the body of any PATCH request to the entity module requires the following structure and data conventions.

• Fields –Field data with target value for update.

The “fields” section is used to pass in the fields to update and the desired value. Any omitted fields will be unchanged.

JSON example of updating the values of multiple “cust” fields:

{

“fields”: {

“cust_field_1”: “A”,

“cust_decimal_2: 1.234

}

}

Response Statuses

A non-paginated representation of the updated resource will be returned in the body of the HTTP response in the desired format.

• 200 – Ok

The resource was successfully updated.

• 400 - Bad Request

The request was invalid. This could be due to data validation failures, permission errors, or other missing or incomplete requirements.

IB Shipment

Field	Type	Description
cust_date_1	Date
cust_date_2	Date
cust_date_3	Date
cust_date_4	Date
cust_date_5	Date
cust_decimal_1	Decimal
cust_decimal_2	Decimal
cust_decimal_3	Decimal
cust_decimal_4	Decimal
cust_decimal_5	Decimal
cust_field_1	String
cust_field_2	String
cust_field_3	String
cust_field_4	String
cust_field_5	String
cust_long_text_1	String
cust_long_text_2	String
cust_long_text_3	String
cust_number_1	Integer
cust_number_2	Integer
cust_number_3	Integer
cust_number_4	Integer
cust_number_5	Integer
cust_short_text_1	String
cust_short_text_2	String
cust_short_text_3	String
cust_short_text_4	String
cust_short_text_5	String
cust_short_text_6	String
cust_short_text_7	String
cust_short_text_8	String
cust_short_text_9	String
cust_short_text_10	String
cust_short_text_11	String
cust_short_text_12	String

IB Shipment Detail

Field	Type	Description
cust_date_1	Date
cust_date_2	Date
cust_date_3	Date
cust_date_4	Date
cust_date_5	Date
cust_decimal_1	Decimal
cust_decimal_2	Decimal
cust_decimal_3	Decimal
cust_decimal_4	Decimal
cust_decimal_5	Decimal
cust_field_1	String
cust_field_2	String
cust_field_3	String
cust_field_4	String
cust_field_5	String
cust_long_text_1	String
cust_long_text_2	String
cust_long_text_3	String
cust_number_1	Integer
cust_number_2	Integer
cust_number_3	Integer
cust_number_4	Integer
cust_number_5	Integer
cust_short_text_1	String
cust_short_text_2	String
cust_short_text_3	String
cust_short_text_4	String
cust_short_text_5	String
cust_short_text_6	String
cust_short_text_7	String
cust_short_text_8	String
cust_short_text_9	String
cust_short_text_10	String
cust_short_text_11	String
cust_short_text_12	String

Item Characteristics

Field	Type	Description
cust_attr_1	String
cust_attr_2	String

Load

Field	Type	Description
cust_field_1	String
cust_field_2	String
cust_field_3	String
cust_field_4	String
cust_field_5	String
cust_field_6	String
cust_field_7	String
cust_field_8	String
cust_field_9	String
cust_field_10	String

Location

Field	Type	Description
cust_field_1	String
cust_field_2	String
cust_field_3	String
cust_field_4	String
cust_field_5	String
to_be_counted_flg	boolean	true false
to_be_counted_ts	date and time	All Date-time objects are assumed to be in the time zone of the user's facility context. JSON: {"field_ts": "2018-01-30T18:30:00"}} XML: <field_ts>2018-01-30T18:30:00</field_ts>

Order Header

Field	Type	Description
cust_date_1	Date
cust_date_2	Date
cust_date_3	Date
cust_date_4	Date
cust_date_5	Date
cust_decimal_1	Decimal
cust_decimal_2	Decimal
cust_decimal_3	Decimal
cust_decimal_4	Decimal
cust_decimal_5	Decimal
cust_field_1	String
cust_field_2	String
cust_field_3	String
cust_field_4	String
cust_field_5	String
cust_long_text_1	String
cust_long_text_2	String
cust_long_text_3	String
cust_number_1	Integer
cust_number_2	Integer
cust_number_3	Integer
cust_number_4	Integer
cust_number_5	Integer
cust_short_text_1	String
cust_short_text_2	String
cust_short_text_3	String
cust_short_text_4	String
cust_short_text_5	String
cust_short_text_6	String
cust_short_text_7	String
cust_short_text_8	String
cust_short_text_9	String
cust_short_text_10	String
cust_short_text_11	String
cust_short_text_12	String
externally_planned_load_flg	Boolean	Only valid if the order is less than Shipped status. When updating the flag to false, any externally_planned_load_nbr values set on the corresponding order details will be removed.
stop_ship_flag	Boolean	Update the stop_ship_flag on the order header if API call made is successful. Allowed order statuses for setting the stop_ship_flag to true: Created, Partially Allocated, Allocated, In-Picking, Picked, In-Packing, Packed, Loaded. If order status is shipped or cancelled, then respond with error. If order status is shipped or cancelled, then respond with error, other statuses should be ok.

Order Detail

Field	Type	Description
cust_date_1	Date
cust_date_2	Date
cust_date_3	Date
cust_date_4	Date
cust_date_5	Date
cust_decimal_1	Decimal
cust_decimal_2	Decimal
cust_decimal_3	Decimal
cust_decimal_4	Decimal
cust_decimal_5	Decimal
cust_field_1	String
cust_field_2	String
cust_field_3	String
cust_field_4	String
cust_field_5	String
cust_long_text_1	String
cust_long_text_2	String
cust_long_text_3	String
cust_number_1	Integer
cust_number_2	Integer
cust_number_3	Integer
cust_number_4	Integer
cust_number_5	Integer
cust_short_text_1	String
cust_short_text_2	String
cust_short_text_3	String
cust_short_text_4	String
cust_short_text_5	String
cust_short_text_6	String
cust_short_text_7	String
cust_short_text_8	String
cust_short_text_9	String
cust_short_text_10	String
cust_short_text_11	String
cust_short_text_12	String

Purchase Order Header

Field	Type	Description
cust_field_1	String
cust_field_2	String
cust_field_3	String
cust_field_4	String
cust_field_5	String

Purchase Order Detail

Field	Type	Description
cust_field_1	String
cust_field_2	String
cust_field_3	String
cust_field_4	String
cust_field_5	String
stop_recv_flg	boolean

Work Order Header

Field	Type	Description
cust_field_1	String
cust_field_2	String
cust_field_3	String
cust_field_4	String
cust_field_5	String

Work Order Kit

Field	Type	Description
cust_field_1	String
cust_field_2	String
cust_field_3	String
cust_field_4	String
cust_field_5	String

Pallet

In order to provide the key to identify the Pallet and update the Weight and Volume fields. a PATCH verb for the Pallet entity is available.

PATCH .../wms/lgfapi/entity/pallet/id/

where id = id of the pallet, which can be obtained using GET method

The following is a JSON sample of the request body:

{

"fields":

{

"lpn_type_id": "123",

"length": "45",

"width": "50.8",

"height": "70",

"actual_weight": "180"

}

}

You can update the following fields using the patch method:

Field	Type	Description
lpn_type_id	String
length	String
width	String
height	String
actual_weight	String

Container, IBLPN, and OBLPN

The legacy API, “update_oblpn_dims”, has been deprecated in place of PATCH requests on three lgfapi entities: container, iblpn, and oblpn. This functionality provides a mechanism to update the container’s dimensional and weight fields. The functionality is the same for each entity. The only difference being that the “container” entity may be used to update both IBLPN and OBLPN’s. The other two entities are restricted to acting on only their given container type.

URL examples:

PATCH .../entity/container/{id}
PATCH .../entity/iblpn/{id}
PATCH .../entity/oblpn/{id}

Supported Fields

• length
• width
• height
• weight
• volume

Supported Options

• calc_volume_flg
  • Boolean (Default = False)
  • When true, the container’s volume will be calculated from the length, width, and height.
  • If the volume is explicitly provided in the “volume” field, this flag is ignored.

Additional Functionality

Updating the container’s weight and dimension fields may trigger some additional updates:

• actual_weight_flg
  • This container flag will be set to true if the weight is updated.
• lpn_type_id
  • Container value will be removed if any of length, width, or height is updated.

Request Body Example 1

Explicitly update all dim and weight values.

{

"fields": {

"length": “1.23”,

"width": “2.24”,

"height": “3.40”,

"weight": “19.25”,

“volume”: “9.37”

}

}

Request Body Example 2

Update only some dim values and request container’s volume be recalculated.

{

"fields": {

"length": “1.23”,

"width": “2.24”

},

"options": {

"calc_volume_flg": true

}

}

Special Note about JSON Decimal Values

When sending decimal values in a JSON request, it is recommended to send them wrapped in double quotes like a string value, as seen in the example above. This will prevent against any loss of precision as part of the lgfapi request.

Entity Operations (GET/POST)

Many entities offer specialized operations in order to assist users in more complicated, or performance intensive operations. These operations can act on one or more resources and may affect entities beyond the one(s) targeted in the request. The URLs may follow a “list” or “retrieve” styles:

Format for an entity operation URL evocable for a specific resource by “id”:

…/wms/lgfapi/v10/entity/{entity_name}/{id}/{operation_name}/

Format for a “bulk” entity operation URL evocable for potentially multiple resources:

…/wms/lgfapi/v10/entity/{entity_name}/{operation_name}/

Entity operations are invoked in the same manner as previously discussed for GET and POST requests. Each operation has its own URL tied to the entity. Entity operations that use a GET request are still for obtaining a representation in the response body and do not modify data. Entity operations that use POST requests trigger an action or series of actions on the entity that can change resource state.

Response Status

Entity operations follow the response statuses previously discussed for GET and POST request, with one addition:

• 204 – No Content

This HTTP response status is returned when the request was successfully fulfilled, but there is no additional content to return to the requester. Users should interpret this as success and expect the response body to be empty.

Bulk Operations

Entities may also support “bulk” operation that allow the same operation to be run on one or more resources within a single request. There are several key differences and additional options that apply to bulk operations.

Parameter Data Filtering

Since bulk operations are capable of acting on one or more objects in a single request, the request body’s “parameter” data is required. This data is a series of one or more filter conditions that will be applied to identify the target list of objects. Each operation may have its own allowed set of filter conditions that can be applied. This may include allowing users to filter on related objects and using complex lookups such as “in” by the same double underscore (“__”) notation as in a GET request’s filters.

Note: all data is still automatically filtered by the user’s eligible facilities and companies and that the user is not permitted to run bulk operations on objects outside their allowed scope.

In general, all bulk operations allow for the filtering of objects by “id”. For example, a JSON request body’s parameters section for filtering on multiple object id’s would be:

{

“paramters”: {

“id__in”: [1, 2, 3]

}

}

Filtering on facility code and company code could be achieved by doing the following (assuming the entity and operation allow it):

{

“parameters”: {

“facility_id__code”: “FAC1”,

“company_id_code”: “COM1”

}

}

The maximum number of objects that may be acted upon in a single request is dictated by the requesting user’s “Rows per Page” attribute. This is configurable per user but also applies in other areas of the application such as how many objects are returned per page in an lgfapi GET request, or in the UI when refreshing a page’s data grid.

Commit Frequency

All bulk operations are provided this additional “options” integer input parameter (default = 0). This parameter allows the requester to dictate at what frequency the changes are applied to each resource or group of resources being processed.

The default value of 0 specifies that no updates are committed unless all resources are processed successfully (all or nothing). All changes are rolled back on the first error, and only the first error is reported back to the user using the stand response.

A value of 1 indicates that the changes should be committed per resource successfully processed. Any error will only cause a failure and roll back of changes for the specific resource that failed. All errors will be accumulated and returned in the standardized bulk response format (see below).

Although a value > 1 is permitted, it is not advised that customers use this unless instructed to do so by support. This is typically only used for more advanced or larger data processing scenarios and for certain performance considerations.

Response Status and Content

When the commit frequency is 0, the bulk operations will give the standard error response format as previously documented, if any error is found. However, a different response status and standardized format is provided on total success or when the commit frequency value is > 0:

A 200 – OK response is returned for bulk operations along with a standardized bulk response having the following attributes:

• record_count – Total number of resources processed in the request.
• success_count – Number of successfully processed resources.
• failure_count – Number of unsuccessfully processed resources.
• details – A nested dictionary (key/value map) that provides additional details for any resources that failed during the processing of the operation.
  • The key to identify each resource and it’s failure is by default the resource’s unique “id” value. However, a different identifying key may be returned per operation, as documented.
  • If no details are provided, the value will be null.

The following is a JSON example where 2 objects were processed, but one (having id=123) failed:

{

“record_count”: 2,

“success_count”: 1,

“failure_count”: 1,

“details”: {

123: “Invalid status.”

}

}