Service jobs
Last updated
Last updated
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 part.
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.
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:
customAttributes
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.
After a custom service has been created, additional Information can be added subsequently via the following API call:
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.
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.
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.
In order to use Custom Service, it must be bound to a facility. This is achieved by creating a Facility Custom Service Connection.
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.
status: Indicates whether this custom service is activated for the given facility
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.
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.
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.
A service job can be created with the following call:
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)
targetTime
The time at which the Service Job is expected to be finished, e.g. 2024-04-03T09:45:51.525Z
lineItemsThe 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 status of a Service Job can be changed by using the following API call
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
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.
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.
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.
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).
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:
Adding a service job link below an existing service job link:
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 section for more details.
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 will be used.
While 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 . A new will be created when a Service Job is created or it will be referenced by an existing when a Service Job Link reference is provided upon Service Job creation.
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 (and ) will be created.
A Linked Service Jobs is a virtual construct that shows the sequence and dependencies between different .
A Linked Service Jobs is automatically created when a 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.
As a Linked Service Job maps the sequence of , it also creates dependencies between them. The order of the is determined by embedding in by adding them to the nextServiceJobLinks array.