Custom service & service jobs
A service job is the actual instance of a custom service in a facility. A custom service is an entity that contains all the information about an offered service. It must be bound to a facility and serves as a blueprint for creating service jobs.
An example of a custom service is the adjustment of a shirt by adding embroidery to the collar and sleeve, as shown in the creation example below. Upon creation, the custom service is available for use at the tenant level. A custom service can also reference another custom service (for instance, when one service requires another to be performed first), forming a chain of up to 25 dependent services.
Because custom services might have varying availability or execution times across different facilities, a facility custom service connection must be established before the service can be employed. This process is described in the Facility custom service connection section.
Custom services
Create a custom service
To create a custom service, execute the following POST request with the JSON body:
POST https://{YOUR-TENANT-NAME}.api.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 a custom service, send a PATCH request with the fields to be changed in the request body:
Custom service additional information
A custom service can contain additional information, which is managed through dedicated API endpoints.
Add or change additional information
To add or change additional information for a custom service, use the following POST and PUT requests with the relevant data in the body:
Delete additional information
To delete additional information from a custom service, execute the following DELETE request:
Facility custom service connection
To employ a custom service, it must be bound to a specific facility. This binding is established by creating a facility custom service connection.
Create or update a facility custom service connection
To create a connection that enables a custom service in a facility, execute a POST request. To update an existing connection, use a PATCH request.
Delete a facility custom service connection
Service jobs
While a custom service serves as a blueprint, a service job is the actual instance of that service in a specific facility. Furthermore, every service job is part of a linked service job. A new linked service job is created automatically with the first service job. Subsequent service jobs can be added to this existing linked service job by providing a reference during their creation.
Create a service job
While service jobs can be created using the API, the system can also create them automatically from an order routing decision, similar to how it creates pick jobs.
A service job can be created either as part of an order via the Order.customServices object or by using the following direct API call:
Create a service job from an order
The customServices object in an order is structured as follows:
In this example, the child custom service requires Item_1, which is also required by the parent custom service. After the order is processed, the system generates the corresponding service jobs.
Child service job (partial)
Parent service job (partial)
The system transfers the required items defined in the custom service to the requiredLineItems field of the corresponding service job. Any items subsequently selected for the job are stored in the lineItems field.
Update a service job
A service job is updated using the actions API endpoint. For details on available actions, refer to the Service Job Actions API reference:
Example body:
Cancel a service job
If a service job in the dependency tree is canceled (e.g., due to unavailable items), all subsequent dependent jobs in the sequence are also automatically canceled.
Service data
Each service job has a serviceData object that contains information about the items that can be selected for it. This object contains the items for the specified service job and all connected service jobs. Through this object, a user can see which item is altered by which service job, the sequence of execution, how many items have been used, and whether the items can be returned after job completion.
Retrieve the serviceData object using the following GET request:
Selecting and unselecting items
When a service job has the status NOT_READY, a user can select the items required for its execution. The job status changes to OPEN once all required items from the order are selected. It is possible to add more items, but items already used by a child job cannot be removed, as they are automatically passed to the parent job. 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. Items are selected or unselected using actions on the serviceData object with the following API calls.
Select items
Unselect items
When selecting items, note that an item used in one branch of a parallel process cannot be used in another parallel branch. However, it can be used in subsequent parent jobs.
However, it is possible to use items that have not yet been assigned in parallel branches.
Linked service jobs
A linked service job is a construct that defines the sequence and dependencies between different service jobs. It contains one or more service job links, each referencing a specific service job.
A linked service job creates dependencies by mapping the execution sequence. The order is determined by nesting service job links within the nextServiceJobLinks array. For example, if the link for service job B contains a reference to service job A in its nextServiceJobLinks array, service job A must be completed before service job B can begin.
The system enforces this dependency by setting the status of service job B to NOT_READY. The status automatically changes to OPEN only after all prerequisite jobs (from the nextServiceJobLinks array) reach a terminal status like FINISHED, CANCELLED, or OBSOLETE. A service job cannot be manually transitioned from NOT_READY to IN_PROGRESS, FINISHED or WAITING_FOR_INPUT.
Service job links
A service job link references a service job and contains an array, nextServiceJobLinks, that points to any subsequent job links. This nested structure within a linked service job maps the execution sequence of all related service jobs.
The system automatically creates a linked service job when the first service job in a sequence is created; it cannot be created manually. However, users can add new service job links to an existing linked service job to customize the workflow.
Inherited line items
When service jobs are sequenced in a linked service job, line items from one job can be inherited by the next. These items appear in the inheritedLineItems array of the subsequent service jobs.
For 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 two line items (a shirt to be tailored and thread for the embroidery) that are involved in this process. The first service job (tailoring) has one line item (the shirt), the following service job (embroidery) has one line item (the thread) and one inherited line item (the shirt), and the last service job (quality check) has no new line items but has two inherited line items (the shirt and the thread).
Add a service job link to a linked service job
A service job link can be added either to the root level of a linked service job or inside an existing service job link.
Add a service job link to the root level
Add a service job link below an existing service job link
Last updated