Service Jobs

Custom Service is an entity that contains all the information on an offered service. It must be bound to a facility and serves as a blueprint. A Service Job is the actual instance of a Custom Service.

An example for a Custom Service would be an adjustment of a shirt by adding an embroidery on the collar and sleeve as it's 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 Custom Service Connection has to be established. This is being described in the Facility Custom Service Connection part.

Orders that are split by routing decisions are currently not supported with Custom Service. We do not recommend activating Order Split when working with Custom Services and Service Jobs.

Creating a Custom Service

POST /api/customservices

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/customservices' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "status": "ENABLED",
    "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"
    }
}'

Mandatory Fields

nameLocalized

This fields sets the name if the Custom Service with it's respective translations. As of October 2023, the following locales are supported: de_DE, en_US, pl_PL, ru_RU, nl_NL, fr_FR, it_IT, nb_NO. The type is a JSON and has to be used as shown in the example above. The respective translation will be used in accordance with the locale of the client requesting the object. If the client requests a locale that has no translation, the default locale of the tenant will be used. If no default locale is set up, the locale en_US is being used.

itemsRequired

The enum itemsRequired indicates whether lineItems are needed in order to execute this Custom Service. The line items are set in the Service Job. The enum can be: MANDATORY or NONE.

status

status is an enum that indicates whether this Custom Service is enabled or disabled by using the corresponding enum: ENABLED or DISABLED.

Optional Fields

descriptionLocalized

In order to add a description about the Custom Service the field descriptionLocalized can be used. Exactly as nameLocalized translations in accordance with the supported locales can be entered as a JSON in this field.

executionTimeInMin

This field is an integer that indicates how many minutes an execution of a custom service needs.

itemsReturnable

Whether an item can be returned after it has undergone this Custom Service is indicated by this boolean.

additionalInformation

This field is an array that contains objects of type additionalInformation. The following fields are part of additionalInformation:

• nameLocalized (mandatory): name of the additional information in JSON format with it's respective translations

• descriptionLocalized (optional): description of the additional information in JSON format with it's respective translations

• valueType (mandatory): indicates whether the value of this additionalInformation is STRING, BOOLEAN, NUMBER, NOVALUE or INPUT_MULTILINE_STRING

• isMandatory (optional): this boolean indicates if this Additional Information is mandatory or not

An example can be seen in the following box:

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

The customAttributes field is a JSON object that carries information that might be relevant to the Custom Service. The form and content of this object is completely free, but its JSON serialized size is limited. Check out the Custom Attributes section for more details.

Updating a CustomService

PATCH /api/customservices

curl -sSL -X PATCH 'https://your.api.fulfillmenttools.com/api/customservices' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "actions": [{
      "action": "ModifyCustomService",
      "status": "ENABLED",
      "nameLocalized":{
        "en_US": "Hemd Initialien Bestickung (italic)",
        "de_DE": "Shirt initials embroidery (kursiv)"
      },
      "descriptionLocalized":{,´
        "en_US": "The desired initials are embroidered on the collar and sleeve in an italic style..",
        "de_DE": "Die gewünschten Initialien werden am Kragen und Ärmel in kursivem Stil eingestickt."
      },
      "executionTimeInMin": 70,
      "itemsReturnable": false,
      "itemsRequired": "MANDATORY"
    }],
    "version": 42
}'

Update a Custom Service by using a PUT on the URL shown above. Enter the respective id of the Custom Service in {custom service id} . The actions array and version are both mandatory. Make sure to enter the correct version of the Custom Service you like to update. Add the desired changes to the object inside the actions array. The only field inside of the object that is mandatory is action, all other fields are optional, meaning you just need to enter those fields which you like to change.

Delete Additional Information of a Custom Service by using DELETE on the URL shown above. Replace {custom service id} with the respective ID.

Adding Additional Information to a Custom Service

After a custom service has been created, additional Information can be added subsequently via the following API call:

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/customservices/{custom service id}/additionalInformation' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "nameLocalized": {
        "en_US": "Thread Material",
        "de_DE": "Faden Material"
      },
      "descriptionLocalized": {
        "en_US": "Material of the thread",
        "de_DE": "Material des Fadens"
      },
      "valueType": "STRING"
 }'

The fields are exactly the same as describe above in the additionalInformation paragraph Custom Service. The id of the Custom Service to which the Additional Information should be added, needs to be entered in the call at {custom service id} in the URL of the post call as shown above in the code example.

Updating Additional Information

curl -sSL -X PUT 'https://your.api.fulfillmenttools.com/api/customservices/{custom service id}/additionalInformation/{additional information id}' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "nameLocalized": {
        "en_US": "Thread Material",
        "de_DE": "Faden Material"
      },
      "descriptionLocalized": {
        "en_US": "Material of the thread",
        "de_DE": "Material des Fadens"
      },
      "valueType": "STRING"
 }'

Update an Additional Information of a Custom Service by using a PUT on the URL shown above. Enter the respective id of the Custom Service in {custom service id} and Additional Service id in {additional service} in the URL.

Deleting Additional Information

curl -sSL -X DELETE 'https://your.api.fulfillmenttools.com/api/customservices/{custom service id}/additionalInformation/{additional information id}' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json'

Delete an Additional Information of a Custom Service by using DELETE on the URL shown above. Replace {custom service id} and {additional information id} with the respective ids.

Facility Custom Service Connection

In order to use Custom Service, it must be bound to a facility. This is achieved by creating a Facility Custom Service Connection.

Creating a Facility Custom Service Connection

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/{facilityId}/customservices/{custom service id}
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "executionTimeInMin": 80,
    "status": "ACTIVE"
}'

Create a Facility Custom Service Connection by using the call above. Replace {facilityId} with the id of the facility the custom service should be added to and {custom service id} with the id of the custom service you like to add to the facility.

Mandatory Fields

status: Indicates whether this custom service is activated for the given facility

Optional Fields

executionTimeInMin: Indicates the time in minutes needed to fulfill this custom service at this facility. If no value is entered in this field, the value of the tenant-wide Custom Service will be used.

Updating a Facility Custom Service Connection

curl -sSL -X PATCH 'https://your.api.fulfillmenttools.com/api/{facilityId}/customservices/{custom service id}
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "executionTimeInMin": 80,
    "status": "ACTIVE"
    "version": 42
}'

Replace {facilityId} with the id of the facility the custom service should be added to and {custom service id} with the id of the custom service you like to add to the facility.

While the field version is mandatory, the other fields executionTimeInMin and status are optional and can be added as the desired update requires them to.

Deleting a Facility Custom Service Connection

curl -sSL -X DELETE 'https://your.api.fulfillmenttools.com/api/{facilityId}/customservices/{custom service id}
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json'

Delete an Additional Information of a Custom Service by using DELETE on the URL shown above. Replace {facilityId} and {custom service id} with the respective IDs.

Getting all Custom Services of a Given Facility

curl -sSL -X GET 'https://your.api.fulfillmenttools.com/api/{facilityId}/customservices/
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json'

Get all Facility Custom Service Connections of a give facility by using the url above. Replace {facilityId} with the corresponding id of the desired facility.

Service Jobs

While Custom Service serves as a blue print, a service Job is the actual instance of a Custom Service. When a Service Job is created it will always be part of a Linked Service Jobs. A new Linked Service Jobs will be created when a Service Job is created or it will be referenced by an existing Linked Service Jobs when a Service Job Link reference is provided upon Service Job creation.

While the following passages show how service jobs can be created via API, they can also be created automatically as an outcome by an Order Routing decision analogous to Pick Jobs.

Creating a Service Job

A service job can be created with the following call:

Create service job

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/servicejobs?customServiceRef={custom service id}
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "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",
          "attributes": [
            {
              "category": "descriptive",
              "priority": 100,
              "key": "Collar Type",
              "value": "Button Down Collar"
            },
            {
              "category": "descriptive",
              "priority": 200,
              "key": "Color",
              "value": "White"
            },
            {
              "category": "descriptive",
              "priority": 300,
              "key": "Material",
              "value": "100% Organic Cotton"
            },
            {
              "category": "descriptive",
              "priority": 300,
              "key": "Size",
              "value": "M - 100"
            }
          ]
        }
      }
    ]
}'

Mandatory Fields

facilityRef

The id of the facility this Service Job should be linked to.

customServiceRef

The id of the Custom Service this Service Job references. It will the contain the following fields of the references Custom Service:

• nameLocalized

• itemsRequired

• descriptionLocalized (if existent in referenced Custom Service)

• executionTimeInMin (if existent in referenced Custom Service)

• itemsReturnable (if existent in referenced Custom Service)

• additionalInformation (if existent in referenced Custom Service)

• customAttributes (if existent in referenced Custom Service)

Note: Subsequent changes to the referenced Custom Service will not affect already created Service Jobs.

targetTime

The time at which the Service Job is expected to be finished, e.g. 2024-04-03T09:45:51.525Z

Optional Fields

lineItems

The line items that will undergo the custom service

processRef

The id of the process this Service Job should be linked to. If no process id will be given a new process with a new process id will be created

operativeProcessRef

A reference to the operative process this service job belongs to.

shortId

A short identifier, e.g. SJ-13

tenantOrderId

The tenant order id of the order this service job is part of.

serviceJobLinkRef

The id of the Service Job Link this Service Job should be added to. If this id is provided a new Service Job Link will be created and added to the nextServiceJobLinks of the referenced Service Job Link. If no reference is provided a new Linked Service Job (and Service Job Link) will be created.

Updating the status of a Service Job

The status of a Service Job can be changed by using the following API call

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/servicejobs/{servicejobid}/actions
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "StartServiceJob",
    "version": 3,
    "additionalInformation": [
      {
        "additionalInformationRef": "{additionalInfoRef}",
        "value": "value"
      }
    ]
}'

Mandatory fields

name

The status the Service Job should be changed to. The following enums are available: StartServiceJob, FinishServiceJob, CancelServiceJob, HoldServiceJob, OpenServiceJob, ObsoleteServiceJob

version

The current version of the Service Job

Optional fields

additionalInformation

The additionalInformation you want to add to the serviceJob when changing the status. This is an array an can contain multiple additionalInformation objects. This field cannot be passed when using the ObsoleteServiceJob action.

Linked Service Jobs

A Linked Service Jobs is a virtual construct that shows the sequence and dependencies between different Service Jobs.

Service Job Links

A Linked Service Jobs consists of 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 following Service Job Links. The structure of the Service Job links within a Linked Service Jobs thus maps the sequence of related Service Jobs.

A Linked Service Jobs is automatically created when a Service Job is created. It is not possible to create a Linked Service Jobs object manually. However, it is possible to add Service Job Links to a Linked Service Job and thus customize the sequence of related ServiceJobs.

Dependencies between Service Job referenced in a Linked 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 in ServiceJobLinks 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 ServiceJob B), Service Job A, which is contained in nextServiceJobLinks, must be executed first before ServiceJob B can be started. This is ensured by the fact that the status of ServiceJob B is initially NOT_READY and only changes (automatically) to OPEN as soon as all ServiceJobs contained in the nextServiceJobLinks array have the status FINISHED, CANCELLED or OBSOLETE. At the same time a status change from NOT_READY to IN_PROGRESS, FINISHED, WAITING_FOR_INPUT is not possible.

Inherited Line Items

As mentioned before, 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 3 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 lineItem (shirt), the following Service Job (embroidery) has 1 line item (thread) and 1 inherited line item (shirt), the last Service Job (quality check) has no line item and 2 inherited line items (shirt, thread).

Adding a ServiceJobLink to a Linked Service Jobs

A serviceJobLink can either be added to the root level of a Linked Service Job or inside an existing serviceJobLink.

Adding a service job link to the root level:

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/linkedservicejobs/{linkedServiceJobId}/servicejoblinks
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "serviceJobRef": "a28835b9-f81a-4f63-96a6-c7e612ebc2a3"
  }'

Adding a service job link below an existing service job link:

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/linkedservicejobs/{linkedServiceJobId}/servicejoblinks/{serviceJobLinkId}
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "serviceJobRef": "a28835b9-f81a-4f63-96a6-c7e612ebc2a3"
  }'