CreateJob

Creates a job with its work orders, one per container or load, in a single request: what Create a job does in TrakIT. Use it when jobs start in another system, such as a booking or customs system. Then read the job with GetJob, record its events with SaveSeqData, and change a work order’s header with UpdateWOHeader.

How to sign in and read the response: Authentication, Responses.

POST /api/v1/CreateJob
Token: your-token
Content-Type: application/json

{
  "WFID": 12,
  "TD": "EXBL2610045",
  "CusID": 3021,
  "ShipperID": 3022,
  "ReceiverID": 3021,
  "JobType": [2],
  "CargoType": 0,
  "IncoTerms": "CIF",
  "Remarks": "Booking received from the customer portal",
  "WOList": [
    {
      "ContNum": "ABCU1234560",
      "TypeCode": "22G1",
      "SealNum": "SL778812",
      "Commodity": "Ceramic tiles",
      "Weight": 21450.5,
      "OpID": 1187,
      "TransID": 2210,
      "ClAgentID": 2304,
      "Resp": "JSMITH",
      "Priority": 3,
      "Remarks": "Check the seal at the gate",
      "CustRemarks": "Delivery before noon",
      "Services": [4, 6]
    },
    {
      "ContNum": "ABCU2345677",
      "TypeCode": "45G1",
      "SealNum": "SL778813",
      "Commodity": "Ceramic tiles",
      "Weight": 24310,
      "OpID": 1187,
      "Resp": "JSMITH",
      "Services": [4]
    }
  ]
}

TrakIT reads the body field by field, by name, and the names are case-sensitive: send WFID, not wfid. A field it does not know is ignored. So is a value it cannot read as the field’s type, for example text in a number field: TrakIT then treats the field as not sent. Send numbers as JSON numbers and lists as JSON lists. A field you leave out stays empty, unless its row below gives a default.

The fields fill in the job’s and work orders’ header fields. The API names them as below.

Job fields

Field	Required	Meaning
WFID	Yes	The workflow of the job: its ID, a whole number, as in the ID column of Workflow Definitions.
TD	No	The job reference, for example the bill of lading number. TrakIT removes spaces, stores it in capitals and keeps the first 30 characters. Only letters A to Z, digits, -, _, , and / are allowed, and no other job can have the same reference. Send it with every job: see Send complete jobs.
CusID	No	The customer: the entity’s ID, as in the ID column of Entity Management.
ShipperID	No	The shipper: an entity ID.
ReceiverID	No	The receiver: an entity ID.
JobType	No	The job types: a list of job type IDs, whole numbers, also for a single one: [2]. TrakIT Support can give you the IDs of your job types.
CargoType	No	The cargo type, as a number: see Cargo types.
IncoTerms	No	The Incoterms: one or more of EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DPU, DAP and DDP, separated by commas, for example CIF or FOB,CIF. At most 100 characters.
Remarks	No	Remarks For Job, shared by all the job’s work orders.
WOList	Yes	The work orders: a list of at least one object, with the fields below.

Work order fields

Each entry of WOList is one work order.

Field	Required	Meaning
ContNum	No	The container number, at most 20 characters. TrakIT stores it as you send it: send it in capitals, without spaces. Two work orders of one request cannot have the same container number.
TypeCode	No	The load type: the code or alternate code of an active load type, for example 22G1. TrakIT stores the load type’s own code.
SealNum	No	The seal number, at most 100 characters: letters A to Z, digits, spaces and # $ % + , - . / @ _.
Commodity	No	The goods, at most 500 characters.
Weight	No	The weight in kilograms, from 0 to 50,000,000. The default is 0.
OpID	No	The carrier: an entity ID.
TransID	No	The transporter: an entity ID.
BondAgentID	No	The bond agent: an entity ID.
ClAgentID	No	The clearing agent: an entity ID.
Resp	No	The responsible person: a user ID, for example JSMITH. The default is the API user.
Priority	No	The work order’s priority, a whole number: 1 Critical, 2 High, 3 Normal, 4 Low or 5 Very Low. The default, also for 0, is 3.
Remarks	No	Internal Remarks.
CustRemarks	No	Remarks For Customer.
Services	No	The work order’s services: a list of service IDs, whole numbers, for example [4, 6]. System administrators see the IDs under Workflow Services in Master Tables. A service that the workflow does not offer is left out.

CreateJob sets only the header fields above. Set the return transporter and Shipper Container afterwards with UpdateWOHeader, events and data fields with SaveSeqData, and other fields, such as the volume, countries and location list, on the work order in TrakIT (Edit work order).

Cargo types

CargoType	Cargo type in TrakIT	CargoType in GetJob
0	Full Container Load (FCL)	FCL
1	Less than Container Load (LCL)	LCL
2	Bulk	Bulk
3	Break-Bulk	BreakBulk
4	Air Freight	Air
5	Charter	Charter
6	Bags	Bags
7	Tanker	Tanker
8	Pallets	Pallets
9	Bales	Bales
10	Boxes/Cartons	Boxes
11	Bagged & Bulk	BagBulk
12	FMCG	FMCG
13	Drums	Drums
14	Jerrycans	Jerrycans
15	Units	Units
16	Vehicles	Vehicles
17	Big Bags	BigBags
18	Empty Container	Empty
99	Other	Other

Rules

TrakIT checks the job first, then each work order in the order of WOList. If a check fails, nothing is created: neither the job nor any of its work orders. Info gives the message but does not say which work order it is about.

Your company can also have validations of its own, set up by TrakIT Support: see Validations & actions. The operations that apply here are Create Job, Save WO Header, Save Job Header and Create WO. Their messages come back in Info the same way.

The request and the job:

Rule	Info when it fails
The Token header holds a valid token.	Token missing in header, Token invalid or expired, or another answer listed in Login token
The user is a system administrator with API access.	API User must be SysAdmin with API Access
The request has a JSON body.	No request body found
WOList is a list of at least one work order.	No WO list found
TD has only the characters allowed.	... is not valid, starting with your installation’s short name for the job reference: by default T/D is not valid
CusID, ShipperID and ReceiverID, when sent, are the IDs of entities.	No such entity
Their mandatory entity data fields are filled in.	Error: Entity '...' Mandatory data field '...' is missing
Your company’s validations for Create Job pass.	Their own messages
No other job has the same reference.	... '...' already exists in workflow ..., starting with your installation’s name for the job reference: by default Transport Document '...' already exists in workflow ...
WFID is the ID of a workflow, and IncoTerms is at most 100 characters.	Unable to create job

Each work order:

Rule	Info when it fails
Services holds whole numbers only.	Service IDs must be integers
Resp, when sent, is not empty.	Responsible Person must be specified.
Weight is from 0 to 50,000,000.	Weight must be in range 0 to 50,000,000 Kg
TypeCode, when sent, is the code or alternate code of an active load type.	Load Type is not valid
If the container is in the container master with a verified load type, TypeCode is that load type.	Load Type '...' does not match Container Master
Commodity holds no script.	Commodity contains invalid characters
SealNum has only the characters allowed.	Seal Number contains invalid characters
Priority is from 1 to 5.	Priority must be between 1 (Urgent) and 5 (On Hold)
SealNum is at most 100 characters.	Seal Number can be a maximum of 100 characters
No earlier work order of the request has the same container number.	WO already exists
Your company’s validations for Save WO Header and Save Job Header pass.	Their own messages
Your installation’s monthly limit on new work orders, if it has one, is not reached.	Monthly limit on WO creation has been reached
Your company’s validations for Create WO pass.	Their own messages
TransID, BondAgentID and ClAgentID, when sent, are the IDs of entities whose mandatory entity data fields are filled in.	No such entity, Error: Entity '...' Mandatory data field '...' is missing
Resp is a user ID, OpID the ID of an entity, ContNum at most 20 characters and Commodity at most 500.	Unable to add new Work Order

Response

On success, Identity is the new job’s ID, and RetInfo holds the job’s ID, its reference and the IDs of its work orders. RowsAffected is 0 and Scalar is null.

{
  "Code": 1,
  "Info": "",
  "RetInfo": {
    "JobID": 10457,
    "BOLNum": "EXBL2610045",
    "WOList": [48211, 48212]
  },
  "RowsAffected": 0,
  "Scalar": null,
  "Identity": 10457
}

Field	Meaning
JobID	The job’s ID, the same as Identity.
BOLNum	The job reference as TrakIT stored it: in capitals, without spaces, at most 30 characters. Read the job with GetJob?Num= and this value.
WOList	The IDs of the new work orders, in the order of WOList in the request. Read each one with GetWO.

Notes

What TrakIT does with a new job

• Each work order gets the events, data fields and KPIs of its workflow that apply to its customer, job types and services, with their default values.
• The data fields of the job’s and work order’s entities are copied to the work order’s events and data where your company has set that up: see Copy values to work orders.
• The job gets its Workflow Serial if the workflow numbers its jobs: see the Serial Format of the workflow settings.
• A container number sent with a load type is added to the container master if it is not there yet.
• Once the job is saved, TrakIT works out the computed data fields, runs the event and data actions that are due, then your company’s actions for Create Job and Create WO. Users who subscribed to Create Job notifications are told about each new work order.
• The job and its work orders are recorded as created by the API user.

Send complete jobs

Send what a user would have to enter on Create a job:

• the job reference, with every job;
• the header fields that your workflow makes Mandatory on its Header Fields tab;
• a commodity from the workflow’s list, if it has one;
• container numbers that are valid for the workflow, and job types and services that it allows.

Retries

A job reference can be used only once. If a request times out and you do not know whether the job was created, look it up with GetJob before you send it again. Sent again, the request is refused with ... already exists in workflow ....