OS1 Services
Container
25min
introduction to containers in the context of logistics, a container is a physical component with a unique id it is the smallest entity unit to represent a shipment in other words, a container is an identifier of one or more physical boxes (or container docid 84wc3sojyiq92xsenyfzo ), including the containers themselves all physical items within a container are identified by their individual scannable ids externally but they all also share the container’s scannable id every container has its own container docid 84wc3sojyiq92xsenyfzo and set of container docid 84wc3sojyiq92xsenyfzo the process of grouping multiple containers together into one container is called container docid 84wc3sojyiq92xsenyfzo ; the opposite of this is de containerization in the event that a container is added to another container, the relationship becomes a parent child relationship in this case, the container which is housing the other container is the parent a container might or might not have children a container marked as a leaf container will only contain items in it moreover, a container can be automatically or manually disposed of if required before diving into the types of containers, let's understand what an item is what is an item? an item is an atomic (indivisible) physical object that does not contain any items or objects within an item might or might not have a tracking id an item can have the following properties name name of the item (example microfibre reversible quilt blanket) description a short description of the item (example microfibre reversible quilt blanket for a single bed (120 gsm) in walnut brown color) cost total money that you have to pay for the item amount (float with 2 precision points) & currency (string) quantity the total number of items (default value 1) measurement value a number quantifying measurement unit a unit of measurement (cm/m/l/ml) for a quick start guide on creating containers, see creating containers types of container containers are the structures that store various items that need to be moved from point a to point b using some of the container types are bag package pallet trolley box the platform tenant has the option to modify the custom attributes of the default container types and/or create additional container types in configurations, the tenant will need to define the size(s) that each container type can take and also if the particular container is reusable creating a container type to create a container type, call the create a new container type endpoint and pass the following parameters in the request body member description validation data type name a unique name that represents a container of this container type pattern ^\[a za z]{3,16}$ minlength 3 maxlength 64 example bag string isleaf defines whether this container type will have actual physical items or not such types of containers are termed leaf containers default false boolean allowedparent rules defining the allowed container types as the parent of a container type minproperties 1 oneof list of container types allowed as the parent of this container type minitems 1 maxitems 16 pattern ^\[a z]{1,16}$ minlength 3 maxlength 64 string callback specifies a callback url that is used to notify the calling of the result status of the call pattern https? \\/\\/(www\ )?\[ a za z0 9@ % \\+ #=]{2,256}\\ \[a z]{2,4}\b(\[ a za z0 9@ % \\+ #?&//=] ) string entitycode unique code of an entity pattern ^(?!0000^$)(\[0 9]\[0 9]\[0 9]\[0 9])$ string 🚧 note note after a container type is created it cannot be deleted and its name and isleaf attributes are immutable request bodies are specified in json format the following examples show a request body for creating a container type and a request body for updating a container type create container type { "name" "bag", "isleaf" false, "allowedparent" { "oneof" \[ "trolley" ], "not" \[ "bag" ] }, { "ttl" "99d", "callback" { "url" "https //examplecallbackurl com", "meta" { "key1" "post ptp type"// optional meta object can not exceed 256 bytes } } } "entitycode" "e 0001" } update container type { "allowedparent" { "oneof" \[ "bag" ], "not" \[ "box" ] }, { "callback" { "url" "https //examplecallbackurl com", "meta" { "key1" "post ptp type"// optional meta object can not exceed 256 bytes } } } } attributes of a container attributes of a container can be divided into one of the following categories base these are the attributes mandated by the platform for the container some of these attributes are mandatory custom these are the attributes that the tenant defines for the containers, to enhance their usability tenants can define custom validations, and also specify for them to be indexed (if it is to be used in filtering apis) or non indexed in the case of a leaf container, custom will have a mandatory attribute named items and non leaf containers will not be allowed to have this attribute attribute name category purpose data type expected tenant id base the id of the tenant to whose data domain the container belongs uuid container id base a system generated unique id for the container varchar scannable tracking id base this is a physically affixed tracking id (such as a barcode) present on the container for tracking it during a logistical process this is to be used by the tenant and operators internally there can be multiple barcodes on a container, generated by the client, the operator, and the tenant, and hence it will be stored as a list the participant id of the creator of the code also needs to be stored with the tracking id this tracking id needs to be reusable for containers like trolleys and cold storage boxes, their tracking ids will be reusable since multiple containers may have sequentially used this tracking id, a search on this tracking id should return the container that is in either created, opened, or closed states (unless the completed containers are specifically asked) the completed state would imply that the container is no longer in use list container type (optional) base this is a type of container in use by the tenant for example, “bag” packed at a pc, “box” carrying a book purchased from amazon varchar parent container id (optional) base the id of the parent container inside which this container is placed varchar is hazmat (optional) base specifies whether the container can contain hazardous materials or not default value false boolean iscontainerizable (optional) base specifies whether the container can be put into other containers default value false boolean attributes 1 to n (indexed) custom custom attributes for a container with indexing the tenant will be able to configure validations, if required, for these attributes key value attributes 1 to n (non indexed) custom custom attributes for a container without indexing the tenant will be able to configure validations, if required, for these attributes key value 📘 note note attributes such as the capacity of a container, or container temperature controlled, while essential to certain businesses, are not required to define a container, and hence they have not been listed under base attributes the attributes can be defined in the custom attributes section by the tenant if needed creating a container to create a container of a particular container type, call the create a container endpoint and pass the following parameters in the request body member description validation data type trackingdetails a tracking id (such as awb) for a container is usually pasted on the container and used for scanning it there can be multiple tracking ids for a container, owned by different operators, and hence it will be stored as a list operator specifies the owner of the tracking id minlength 3 maxlength 64 example delhivery string trackingid id to track the container minlength 1 maxlength 128 example 13212123 string isprimary indicates whether it is a primary tracking id or not if not defined, the first tracking id is used as the primary tracking id default false boolean items the list of items that can be added to a container only if the container type is a leaf cost the cost of the item unit the unit price of the item number amount the value of the amount accurate up to three decimal places number currency currency of the price of the item number value a number quantifying measurement integer unit unit for measurement valid values cm, m, l, ml, nos, g, kg, mm string attributes a map to provide values for the attributes defined in container type configuration apis isreusable indicates whether the container is reusable default false boolean ishazmat indicates whether this container can contain hazardous materials default false boolean callback specifies a callback url that is used to notify the calling of the result status of the call pattern https? //(www )?\[ a za z0 9@ % \\+ #=]{2,256}\\ \[a z]{2,4}\b(\[ a za z0 9@ % \\+ #?&//=] ) string request bodies are specified in json format the following examples show a request body for creating a container and a request body for updating a container create container { "trackingdetails" \[ { "operator" "worldlogistics", "trackingid" "lm691328537cn", "isprimary"\ false } ], "items" \[ { "name" "shirt", "cost" { "unit" { "amount" 10, "currency" "usd" }, "total" { "amount" 100, "currency" "usd" }, "quantity" { "value" 10, "unit" "kg" } } } ], "attributes" { "color" "black" }, "isreusable"\ false, "ishazmat"\ false, { "callback" { "url" "https //examplecallbackurl com", "meta" { "key1" "post ptp type"// optional meta object can not exceed 256 bytes } } } } update container { "attributes" { "color" "red", "capacity weight max" 77 }, "trackingdetails" \[ { "operator" "nationallogistics", "trackingid" "pv691328537xd" } ], "isleaf"\ false } creating containers in a batch batch processing helps to create and update the containers in the batch batch processing supports two methods to supply the container data json csv file upload to create containers in batch, call the create batch request endpoint to update containers in batch, call the update batch request endpoint attributes for batch request member description validation data type payload list of valid objects to create data in containers maxitems 1024 minitems 1 refid reference id received for each container create request string trackingdetails (optional) field to represent tracking id (such as awb) for a container which is usually pasted on the container and used for scanning it there can be multiple tracking ids for a container, owned by different operators and hence it will be stored as a list operator field to specify the owner of the tracking id minlength 3 maxlength 64 example delhivery string trackingid tracking id minlength 1 maxlength 128 example 132121232423232 string isprimary it defines whether it is a primary tracking id or not if none of the tracking details is set as primary we assume the first tracking id as a primary tracking id default false boolean attributes (optional) a map to provide values for the attributes defined in container type configuration apis items (optional) list of items can be added to a container only if the container type is a leaf name name of the item minlength 3 maxlength 128 example pant/shirt string code (optional) code of the item minlength 3 maxlength 128 string cost cost of the item unit (optional) represents unit price of the item amount (optional) the value of the amount is accurate to three decimal places number currency (optional) currency of the price of the item string total represents the total price of the item amount (optional) the value of the amount is accurate to three decimal places number currency (optional) currency of the price of the item string quantity (optional) quantity > value (optional) a quantifying number measurement integer quantity> unit (optional) unit for measurement enum \[ cm, m, l, ml, nos, g, kg, mm ] string ishazmat (optional) represents whether this container can contain hazardous materials or not default false boolean iscontainerizable (optional) defines whether containers can be put into other containers or not default true boolean callback (optional) represents callback url, which can be to notify status(success/failed) of api 📘 note note the items marked ( ) are mandatory attributes required while creating the containers via batch processing the request bodies are specified in json format the following examples show request bodies for creating and updating containers in batches create containers in batch { "payload" \[ { "refid" "123", "trackingdetails" \[ { "operator" "amazon", "trackingid" "132121232423232", "isprimary" false } ], "attributes" { "weight" 30 } }, { "refid" "456", "trackingdetails" \[ { "operator" "myntra", "trackingid" "99", "isprimary" false } ], "attributes" { "weight" 30 } } ] } update containers in batch { "payload" \[ { "containerid" "batch 3fe393b3 94d6 4fe6 b6e3 xxxxxxxxx", //use actual containerid "data" { "trackingdetails" \[ { "operator" "mumbai", "trackingid" "1321212324232327", "isprimary" false } ], "attributes" { }, "ishazmat" false, "iscontainerizable" true } } ] } 👍 container batch processing a container can be created and updated in batch using batch processing api here are the sample csv files for batch creation & updation of containers creating custom attributes custom attributes can be created by specifying the following parameters to create custom attributes for a container, call the update container type attributes and pass the following parameters in the request body custom attributes custom attributes learn about custom attributes ownership docid\ joymsnhaszoobkikup5ow member description validation data type name name of the attribute to add pattern ^\[a za z ]{1,32}$ example capacity minlength 3 maxlength 64 string datatype specifies the data type of the attribute valid values string, number, boolean, object, array valid values string, number, boolean, object, array string description description of the attribute minlength 1 maxlength 256 string indexed specifies whether the attribute is indexed filter or search operation on the basis of a custom attribute will be only allowed if this field is set as true boolean isreadpublic true all apps can read the custom attributes false (default) only cao and oto will be able to read the custom attributes ownership docid\ joymsnhaszoobkikup5ow default false boolean validation specifies the validations that are performed on the attribute when a container of this type is created or updated range specifies the range that the attribute value must lie in the case of the "string" data type, the range will be the length of the string value \[ min the min value, inclusive max the max value, inclusive ] number valueoneof enum of accepted values minitems 1 required specifies whether the value is required or optional default false boolean callback specifies a callback url that is used to notify the calling of the result status of the call pattern https? \\/\\/(www\ )?\[ a za z0 9@ % \\+ #=]{2,256}\\ \[a z]{2,4}\b(\[ a za z0 9@ % \\+ #?&//=] ) string request bodies are specified in json format the following examples show a request body for creating a container and a request body for updating a container { "attributes" \[ { "name" "capacity", "datatype" "string", "description" "volume attribute", "tags" \[ "volume", "quantity" ], "indexed" true, "isreadpublic" false, "defaultvalue" "four", "validation" { "range" { "min" 3, "max" 100 }, "valueoneof" \[ "bag","box" ], "required" false }} ], { "callback" { "url" "https //examplecallbackurl com", "meta" { "key1" "post ptp type"// optional meta object can not exceed 256 bytes } } } } 📘 important note regarding custom attribute creation important note regarding custom attribute creation if the attribute is already defined for the container type, the validation rules are updated if the attribute is not defined for the container type, it is added as a new core attribute for the container type on successful execution of the call, all updates including changes in data type take effect immediately for the container type lifecycle of a container the lifecycle depicts the current status of a container a container typically can move between different states and substates, basis the workflows set in the application using it the platform will provide a default of four states for a container created specifies the creation of a container the system also generates a unique container id for the container at this time opened signifies readiness of container to begin containerization operations (i e addition or removal of other containers/packages/boxes/items) a child container cannot be “opened” if the parent container is “closed” closed signifies termination of the containerization process; at this point, no further containers/packages/boxes/items may be added to the container a parent container cannot be “closed” if a child container is “opened” completed end of the lifecycle of a container when a container is de containerized, the status of the container will automatically shift to this state 👍 info info state machine service provides the tenant an option to introduce sub states under each of the states and the rules governing the corresponding state transitions containerization all physical items in a container can be identified by their individual tracking ids but also share the container’s tracking id the process of grouping together boxes (or items or containers) into a container is called containerization ; the opposite of this is de containerization in the event that a container is added to a container, the relationship will be a parent child relationship with the largest container containing all other containers (and their constituents) being the parent all operations performed on the parent container are automatically inherited by the child containers (e g all scan events on the parent container are automatically propagated to the child containers) conditions for containerization parent container state should be opened the child container state should be closed parent container should have isleaf property as false child container should have iscontainerizable as true tenant level configurability and extensibility the tenants have the following configurations available to them attributes tenants have full control over defining container types and the respective sizes for the containers for example, a bag can be 3x3 ft and 6x6 ft they can also specify if a particular container type is reusable tenants can define a set of custom indexed and non indexed attributes for every container type tenants can define the duration after which they would like to move inactive containers to the data warehouse (default 72 hours) the tenant can define whether the container is a leaf container (by using the isleaf base attribute) if the tenant defines a leaf container, further, he has to define the “items” attribute as a custom attribute lifecycle tenants have the option to define a list of event names for transition tenants can define sub states (i e , custom lifecycle) for a particular container type for each state, tenants have the option to define a set of sub states and the corresponding rules for state transition as defined in the state machine documentation bulk containerization/decontainerization grouping together containers into a container the container that goes inside another container is said to be containerized attributes for bulk containerization bulk containerization/decontaizerization can be done by specifying the below given attributes use the bulk containerization/decontaizerization api endpoint member description validation data type parentid field to represent container id of the parent container during the containerization process, this value is assigned to represent which container contains this container nullable true example box 9c9b1138 7cdd 11eb 9439 0242ac130002 string childcontainertype field to represent container type of the child containers example box string childids field to represent container ids of the child containers example list \[ "box 9c9b1138 7cdd 11eb 9439 0242ac130002", "box 9c9b1138 7cdd 11eb 9439 0242ac130003" ] string substate (optional) field to represent substate of the closed to state to which the parent container has to be transitioned post containerization required in case of containerization example closed string trackingdetails (optional) field to represent tracking id (such as awb) for a container which is usually pasted on the container and used for scanning it there can be multiple tracking ids for a container, owned by different operators and hence it will be stored as a list operator field to specify the owner of the tracking id minlength 3 maxlength 64 example delhivery string trackingid minlength 1 maxlength 128 example 132121232423232 string isprimary (optional) it defines whether it is a primary tracking id or not if none of the tracking details are set as primary we assume the first tracking id is a primary tracking id default false boolean attributes a map to provide values for the attributes defined in container type configuration apis items a list of items can be added to the container only if the container type is a leaf scannableid (optional) string ishazmat represents whether this container can contain hazardous materials or not default false boolean iscontainerizable (optional) defines whether a container can be put into other containers or not default true boolean isreusable (optional) defines whether the container is re usable or not default false boolean action field to represent an action to be performed on the container enum containerize, decontainerize example containerize string callback (optional) example https //delhivery requestcatcher com string (uri) 📘 note note mandatory fields for bulk containerization/decontainerization if parantid is unavailable, then we create the parent instance and for the parent instance, these attributes are required else these are optional check how to implement how to bulk containerize/decontainerize docid\ wtyhmdfkzpvpwetxlcziu