Custom service & service jobs
A service job is the actual instance of a custom service in a facility. Custom service is an entity that contains all the information on an offered service. It must be bound to a facility and serve as a blueprint.
An example of a custom service is the adjustment of a shirt by adding embroidery to the collar and sleeve, as shown in the following creation example. With the creation, the custom service is available for use on tenant level. A custom service can also reference another custom service (such as when one service requires another to be done first), up to a maximum depth of 25 (A -> B -> C ... -> Y).
As custom services could be available (or not) in different facilities or could have differences in execution time due to different reasons, before being able to use custom services, a facility's custom service connection has to be established. This is being described in the facility custom service connection part.
Custom services
Creating a custom service
Create a custom service by executing the following POST call with the JSON body:
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/customservices{
"status": "ACTIVE",
"nameLocalized": {
"en_US": "Shirt initials embroidery",
"de_DE": "Hemd Initialien Bestickung"
},
"descriptionLocalized": {
"en_US": "The desired initials are embroidered on the collar and sleeve.",
"de_DE": "Die gewünschten Initialien werden am Kragen und Ärmel eingestickt."
},
"executionTimeInMin": 60,
"itemsReturnable": false,
"itemsRequired": "MANDATORY",
"additionalInformation": [
{
"nameLocalized": {
"en_US": "Number of threads",
"de_DE": "Anzahl der Fäden"
},
"descriptionLocalized": {
"en_US": "This value indicates how many threads should be used for the embroidery",
"de_DE": "Dieser Wert gibt an, wie viele Fäden bei der Stickerei genutzt werden sollen"
},
"valueType": "NUMBER",
"isMandatory": true
},
{
"nameLocalized": {
"en_US": "Color",
"de_DE": "Farbe"
},
"descriptionLocalized": {
"en_US": "Color of the embroidery",
"de_DE": "Die Farbe der Stickerei"
},
"valueType": "NUMBER",
"isMandatory": true
}
],
"customAttributes": {
"actionId": "b1eef2b0-1d5c-4819-bddc-b562beb14838"
}
}Update a custom service
To update data in a custom service, call the following URL with the data that would be changed in the body:
PATCH https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/customservices/{customServiceId}{
"status": "INACTIVE"
}Custom service additional information
A custom service can contain additional information. This information can be edited with special API endpoints.
Add/change additional information to/from a custom service
To add or change additional information to/from a custom service, call the following URL with the data in the body that would be changed:
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/customservices/{customServiceId}/additionalinformationPUT https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/customservices/{customServiceId}/additionalinformation/{additionalInformationId}{
"nameLocalized": {
"en_US": "Thread Material",
"de_DE": "Faden Material"
},
"descriptionLocalized": {
"en_US": "Material of the thread",
"de_DE": "Material des Fadens"
},
"valueType": "STRING"
}Delete additional information
To delete additional information from a custom service, call the following URL:
DELETE https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/customservices/{customServiceId}/additionalinformation/{additionalInformationId}Facility custom service connection
To use custom services, it must be bound to a specific facility. This is achieved by creating a facility custom service connection.
Create/update a facility custom service connection
To create a custom service connection to use the custom service in a facility, the following API call must be executed (use PATCH for an update:
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/facilities/{facilityId}/customservices/{customServiceId}{
"executionTimeInMin": 90,
"status": "ACTIVE"
}Delete a facility custom service connection
DELETE https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/facilities/{facilityId}/customservices/{customServiceId}Service jobs
While a custom service serves as a blueprint, a service job is the actual instance of a custom service in a specific facility. Furthermore, when a service job is created, it will always be part of a linked service job. A new linked service job will be created when a service job is created, or it will be referenced by an existing linked service job when a service job link reference is provided upon service job creation.
Create a service job by API
The following passage shows how service jobs can be created via API, they can also be created automatically as an outcome of an order routing decision analogous to pick jobs.
A service job can be created with the Order.customServices object or with the following API call:
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/servicejobs{
"customServiceRef": "sad5622-gfd1-441v-132h-23refsfsass",
"processRef": "a28835b9-f81a-4f63-96a6-c7e612ebc2a3",
"facilityRef": "8a5b283a-bcf9-4f63-132h-v93ca6ea011n3",
"lineItems": [
{
"quantity": 15,
"scannableCodes": [
"0799439112766"
],
"article": {
"tenantArticleId": "100029-W",
"title": "White Shirt",
"imageUrl": "https://cdn11.bigcommerce.com/s-2fhihzl616/images/stencil/960w/products/6562/24857/Mens_White_Cotton_Shirt_MS236LS_4__24507.1645457383.jpg"
}
}
]
}Create a service jobs with order
The custom services in the order would look like this in this Example:
{
// Order
...
"customServices":[
{
"customServiceDefinition":{
"customServiceRef": "CustomServiceRef_Parent"
},
"articleItems":[],
"customServiceItems":[
{
"customServiceDefinition":{
"customServiceRef": "CustomServiceRef_Child"
},
"articleItems":[
{
"tenantArticleRef": "Item_1",
"quantity":1
}
],
"customServiceItems":[]
}
]
}
]
}This would mean that the child custom Service needs "Item_1", and this item is also needed in the parent custom service. After inserting the Order, this would transform to the following Service Jobs.
Child Service Job (Partial):
{
"id": "ServiceJob_Child",
"requiredLineItems": [
{
"article": {
"tenantArticleRef": "Item_1"
},
"quantity": 1
}
],
"lineItems": []
}Parent Service Job (Partial):
{
"id": "ServiceJob_Parent",
"requiredLineItems": [
{
"article": {
"tenantArticleRef": "Item_1"
},
"quantity": 1
}
],
"lineItems": []
}The items required for a service job are stored in the corresponding custom service and transferred to the service job. The required items for a service job appear in the requiredLineItems field after the transition from the custom service to the service job. Selected items are stored in the lineItems field.
Update a service job
The data of a service job can be updated with the actions API endpoint. For detailed update information, check the service jobs action API documentation:
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/servicejobs/{serviceJobId}/actionsExample body:
{
"name": "StartServiceJob",
"additionalInformation": [
{
"additionalInformationRef": "{additionalInfoRef}",
"value": "value"
}
],
"version": 3
}Cancel a service job
If a node in the service job tree is canceled because, for example, the required items are not available or the desired process cannot be executed, all nodes following this node are also canceled.
Service data
A service job has a service data object that contains information about the items that can be selected for the service job. The service data object contains not only the items of the service job, but the items of all connected service jobs. Through is object it can be seen which item it altered by which service job, in which sequence these service jobs have been executed, how many items have already been used and whether the items can be returned after the service job has been completed.
{
"id": "IdServiceData",
"serviceJobRefs": ["IdServiceJobA", "IdServiceJobB"],
"availableLineItems": [
{
"id": "IdAvailableLineItem",
"article": {
"TenantArticleId": "TenantArticleId",
"title": "Title"
},
"quantity": 4,
"availableQuantity": 0,
"executedServiceJobData": [
{
"serviceJobRef": "ABC",
"sequence": 1,
"appliedQuantity": 4,
"itemsReturnable": true
},
{
"serviceJobRef": "DEF",
"sequence": 2,
"appliedQuantity": 4,
"itemsReturnable": false
}
]
}
]
}The service data object can be retrieved with the following API call:
GET https://{YOUR-TENANT-NAME}.fulfillmenttools.com.com/api/servicejobs/{serviceJobId}/servicedataSelecting and unselecting items
If a service job has the status NOT_READY, the items required for execution can be selected. These items must be included in the order so that the service job can change to the status OPEN. It is possible to add further items, but it is not possible to remove items that have already been used in a child node; these are automatically passed on to the parent node. The items required for a service job are stored in the corresponding custom service and transferred to the service job. The required items are stored in the custom service in the articleItems field and appear in the requiredLineItems field after the transition from the custom service to the service job. Selected items are stored in the lineItems field. The items are selected using the service data assigned to the service job and the following API calls:
Select items
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com.com/api/servicejobs/{serviceJobId}/servicedata/actions{
"name": "SELECT_ITEMS_FOR_SERVICE_JOB",
"serviceJobVersion": 3,
"serviceItemsToSelect": [
{
"serviceItemRef": "{ServiceItemRefFromServiceData}",
"quantity": 2
}
]
}Unselect items
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/servicejobs/{serviceJobId}/servicedata/actions{
"name": "UNSELECT_ITEMS_FOR_SERVICE_JOB",
"serviceJobVersion": 3,
"serviceItemsToUnselect": [
{
"serviceItemRef": "{ServiceItemRefFromServiceData}",
"quantity": 2
}
]
}When selecting items, it should be noted that items that have already been used in one branch cannot be used in another parallel branch, but only in the subsequent parent nodes. An example of this is:
Order: Item_1, Item_2, Item_3, Item_4
---A---
/ \
---B--- ---C---
(Item_1) (Item_1) <- not possibleHowever, it is possible to use items that have not yet been assigned in parallel branches.
Order: Item_1, Item_2, Item_3, Item_4
---A---
/ \
---B--- ---C---
(Item_1) (Item_3) <- possibleLinked service jobs
A linked service job is a construct that shows the sequence and dependencies between different service jobs. It contains service job links to hold links to different service jobs.
As a linked service job maps the sequence of service jobs, it also creates dependencies between them. The order of the service jobs is determined by embedding service job links by adding them to the nextServiceJobLinks array.
Example: If a service job link (referencing service job A) is in the nextServiceJobLinks array of another service job link (referencing service job B), service job A, which is contained in nextServiceJobLinks, must be executed first before service job B can be started. This is ensured by the fact that the status of service job B is initially NOT_READY and only changes (automatically) to OPEN as soon as all service jobs contained in the nextServiceJobLinks array has the status FINISHED, CANCELLED or OBSOLETE. At the same time, a status change from NOT_READY to IN_PROGRESS, FINISHED or WAITING_FOR_INPUT is not possible.
Service job links
A service job link holds a reference to a service job and to previous service job links. It also holds an array of the following service job links. The structure of the service job links within a linked service job thus maps the sequence of related service jobs.
A linked service job is automatically created when a service job is created. It is not possible to create a linked service job object manually. However, it is possible to add service job links to a linked service job and thus customize the sequence of related service jobs.
Inherited line items
A sequence for service jobs can be dictated by putting them into relation via a linked service job. Line items that undergo multiple service jobs in a sequence are inherited by being added to the array inheritedLineItems of the following service jobs.
Example: Imagine a custom-tailored shirt that receives an embroidery and undergoes a quality check at the end. There are three service jobs (custom tailoring, embroidery, and quality check) and 2 line items (shirt to be tailored, thread that is used for the embroidery) that are involved in this process. The first service job (tailoring) has 1 line item (shirt), the following service job (embroidery) has 1 line item (thread) and one inherited line item (shirt), the last service job (quality check) has no line item and 2 inherited line items (shirt, thread).
Adding service job link to linked service job
A service job link can either be added to the root level of a linked service job or inside an existing service job link.
Adding a service job link to the root level
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/linkedservicejobs/{linkedServiceJobId}/servicejoblink{
"serviceJobRef": "a28835b9-f81a-4f63-96a6-c7e612ebc2a3"
}Adding service job link below existing service job link
POST https://{YOUR-TENANT-NAME}.fulfillmenttools.com/api/linkedservicejobs/{linkedServiceJobId}/servicejoblinks/{serviceJobLinkId}{
"serviceJobRef": "a28835b9-f81a-4f63-96a6-c7e612ebc2a3"
}Last updated