Find BoxTop job
Finds a customer’s job in Descartes BoxTop by their reference or by job number, for example to check whether a shipment already has one.
@lainstack/boxtop/find-job · TMS · Available on Lainstack Cloud
How to use it
Section titled “How to use it”Use Find BoxTop job to find one of a customer’s jobs in Descartes BoxTop, for example to check whether a shipment already has a job before you create one.
Good to know:
- Find by chooses how to search, and the block shows only that field. An empty value fails the step and says which one, without calling BoxTop.
- By Reference, Account number is required. A reference can match several jobs. job is then the newest by job date, and matchCount says how many matched.
- By Job number, Account number is optional. BoxTop’s job number search takes no account, so if you enter one the block compares it itself, and a job on a different account, or on none, counts as Not found.
- The block leaves on Found or Not found. Not found means job is empty and matchCount is 0. A wrong API address can answer the same way on a Job number search, so it does not prove the job is absent. Check this before you create a job from it.
- A draft run calls this block for real, because it only reads. It changes nothing in BoxTop.
- A Sample data connection answers from a fixed set of fictional records and calls nothing, so you can build and run an automation before you have a BoxTop key. sample is true on those answers.
- If BoxTop refuses the request or does not accept the key, the step fails with the HTTP status and never shows BoxTop’s reply. A rate limit or server error also fails the step, and is worth trying again. Each request has 30 seconds to finish.
Settings
Section titled “Settings”| Setting | Key | Type | Details |
|---|---|---|---|
| BoxTop connection (required) | credentialId |
Connection | Use a Sample data connection until you have a BoxTop key. At most 160 characters. |
| Find by | findBy |
One of Reference, Job number |
Default reference. |
| Reference | reference |
Text | The customer’s reference on the job. |
| Job number | jobNumber |
Text | The BoxTop job, up to 12 characters. Find or create BoxTop job returns it. |
| Account number | accountNumber |
Text | The customer’s BoxTop account, up to 8 characters. Needed to find by Reference. With a Job number it’s optional, and a job on another account counts as Not found. |
Outputs
Section titled “Outputs”| Output | Path | Type |
|---|---|---|
| Job > Job Number | job.jobNumber |
Text |
| Job > Job Date | job.jobDate |
Text |
| Job > Customer Account | job.customerAccount |
Text |
| Job > Customer Reference | job.customerReference |
Text |
| Job > Customs Clearance | job.customsClearance |
Text |
| Job > Job Type | job.jobType |
Text |
| Job > Mode | job.mode |
Text |
| Job > Customer Name | job.customerName |
Text |
| Job > Shipper Name | job.shipperName |
Text |
| Job > Shipper Address | job.shipperAddress |
Text |
| Job > Shipper Country | job.shipperCountry |
Text |
| Job > Consignee Name | job.consigneeName |
Text |
| Job > Consignee Address | job.consigneeAddress |
Text |
| Job > Consignee Country | job.consigneeCountry |
Text |
| Job > Carrier Name | job.carrierName |
Text |
| Job > Commodity | job.commodity |
Text |
| Job > Description | job.description |
Text |
| Job > Nature And Quantity | job.natureAndQuantity |
Text |
| Job > Marks And Numbers | job.marksAndNumbers |
Text |
| Job > Packages | job.packages |
Number |
| Job > Weight | job.weight |
Number |
| Job > Weight Unit | job.weightUnit |
Text |
| Job > Container Type | job.containerType |
Text |
| Job > Container Count | job.containerCount |
Number |
| Job > House Number | job.houseNumber |
Text |
| Job > Bl Number | job.blNumber |
Text |
| Job > Vessel | job.vessel |
Text |
| Job > Voyage Number | job.voyageNumber |
Text |
| Job > Origin Port | job.originPort |
Text |
| Job > Destination Port | job.destinationPort |
Text |
| Job > Departure Date | job.departureDate |
Text |
| Job > Arrival Date | job.arrivalDate |
Text |
| Job > Eta | job.eta |
Text |
| Job > Terms | job.terms |
Text |
| Job > Ucr | job.ucr |
Text |
| Job > Customs Value | job.customsValue |
Number |
| Job > Currency | job.currency |
Text |
| Job > Entry Number | job.entryNumber |
Text |
| Job > Entry Date | job.entryDate |
Text |
| Match Count | matchCount |
Number |
| Sample | sample |
Yes or no |
| Exit | Port | Notes |
|---|---|---|
| Found | found |
|
| Not found | not_found |