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.

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.

Working with service jobs

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:

POST https://{YOUR-TENANT-NAME}.api.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 job from an order

You can only add up to maximum 15 custom services on one level and up to 50 custom services per order.

The customServices object in an order is structured as follows:

{
  // Order
  ...
  "customServices":[
    {
      "customServiceDefinition":{
        "customServiceRef": "CustomServiceRef_Parent"
      },
      "articleItems":[],
      "customServiceItems":[
        {
          "customServiceDefinition":{
            "customServiceRef": "CustomServiceRef_Child"
          },
          "articleItems":[
            {
              "tenantArticleRef": "Item_1",
              "quantity":1
            }
          ],
          "customServiceItems":[]
        }
      ]
    }
  ]
}

In this example, the child customService requires Item_1, which is also required by the parent customServices. After the order is processed, the system generates the corresponding 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 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, see the Service Job Actions API reference:

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/servicejobs/{serviceJobId}/actions

Example body:

{
  "name": "StartServiceJob",
  "additionalInformation": [
    {
      "additionalInformationRef": "{additionalInfoRef}",
      "value": "value"
    }
  ],
  "version": 3
}

Cancel a service job

If a service job in the dependency tree is canceled (for example, 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.

{
  "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
        }
      ]
    }
  ]
}

Retrieve the serviceData object using the following GET request:

GET https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/servicejobs/{serviceJobId}/servicedata

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's possible to add more items, but items already used by a child job can't 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

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.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}.api.fulfillmenttools.com/api/servicejobs/{serviceJobId}/servicedata/actions

{
  "name": "UNSELECT_ITEMS_FOR_SERVICE_JOB",
  "serviceJobVersion": 3,
  "serviceItemsToUnselect": [
    {
      "serviceItemRef": "{ServiceItemRefFromServiceData}",
      "quantity": 2
    }
  ]
}

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.

Order: Item_1, Item_2, Item_3, Item_4
          ---A---
        /        \
    ---B---    ---C---
    (Item_1)   (Item_1)  <- Not possible

However, it's 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)  <- Possible

Linked service jobs

A linked service job 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 can't 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 can't 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, 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

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/linkedservicejobs/{linkedServiceJobId}/servicejoblink

{
  "serviceJobRef": "a28835b9-f81a-4f63-96a6-c7e612ebc2a3"
}

Add a service job link below an existing service job link

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/linkedservicejobs/{linkedServiceJobId}/servicejoblinks/{serviceJobLinkId}

{
  "serviceJobRef": "a28835b9-f81a-4f63-96a6-c7e612ebc2a3"
}