Find or create BoxTop job
Finds the job for a reference in Descartes BoxTop, or creates it, so a repeat never makes a duplicate.
@lainstack/boxtop/create-job · TMS · Available on Lainstack Cloud
How to use it
Section titled “How to use it”Use Find or create BoxTop job to get the job for a customer’s reference in Descartes BoxTop. It looks for a job with that Account number and Reference first and uses it, because BoxTop’s API documents no duplicate protection. If there is none, it creates one with your Job prefix and reads it back.
Good to know:
- The block leaves on Created or Existing. Connect both to the next block to run it either way. Several matches use the first BoxTop lists. A job with a blank reference never matches.
- An existing job is used as it is, and your new values are ignored. BoxTop’s help lists no general job update.
- We don’t yet know which of these fields BoxTop’s customs tab shows.
- If the read-back finds nothing or fails, the step fails and says the job may exist.
- A value over BoxTop’s documented length fails the step before anything is sent and names the setting. A date wired from an earlier step must be a date source.
- If BoxTop refuses the job, the step fails with the HTTP status and never its reply. A rate limit, server error or timeout on the create says the job may have landed.
- Running a step again: a step never repeats by itself, but a person or a resume can run it again. It searches first, so it finds a job that landed. If BoxTop can’t list it yet, it creates a second one.
- Draft runs: a draft run holds this block, searches for nothing and shows the job as Would write. With no pin and no earlier real run, the branch goes on through Created with a job built from your settings, a made-up job number and sample true.
- Sample data: a Sample data connection finds its own fictional jobs, such as PO-4417 on account NGS001. Any other reference gets a job built from your settings. Nothing is sent, and sample is true.
- Not checked against real BoxTop: we have only its docs, from about 2014. How a search matches a reference, how the key is sent, how parties are stored and how soon a new job is listed are unconfirmed.
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. |
| Job prefix (required) | prefix |
Text | Starts the job number BoxTop gives a new job. |
| Account number (required) | accountNumber |
Text | The customer’s BoxTop account, up to 8 characters. |
| Reference (required) | reference |
Text | The customer’s reference. A job with this reference is used, not duplicated. |
| Job type | jobType |
Text | BoxTop’s docs list no allowed values, so use what your site uses. |
| Mode | mode |
Text | BoxTop’s docs list no allowed values, so use what your site uses. |
| Customer name | customerName |
Text | |
| Shipper name | shipperName |
Text | |
| Shipper address | shipperAddress |
Text | |
| Shipper country | shipperCountry |
Text | A two-letter country code. |
| Consignee name | consigneeName |
Text | |
| Consignee address | consigneeAddress |
Text | |
| Consignee country | consigneeCountry |
Text | A two-letter country code. |
| Carrier | carrierName |
Text | |
| Commodity | commodity |
Text | |
| Description | description |
Text | |
| Nature and quantity | natureAndQuantity |
Text | |
| Marks and numbers | marksAndNumbers |
Text | |
| Packages | packages |
Number | |
| Weight | weight |
Number | |
| Weight unit | weightUnit |
Text | |
| Container type | containerType |
Text | |
| Container count | containerCount |
Number | |
| House number | houseNumber |
Text | |
| BL number | blNumber |
Text | |
| Vessel | vessel |
Text | |
| Voyage | voyageNumber |
Text | |
| Origin port | originPort |
Text | |
| Destination port | destinationPort |
Text | |
| Departure | departureDate |
Date | |
| Arrival | arrivalDate |
Date | |
| ETA | eta |
Date | |
| Terms | terms |
Text | BoxTop’s docs list no allowed values, so use what your site uses. |
| UCR | ucr |
Text | |
| Customs value | customsValue |
Number | |
| Customs value currency | currency |
Text | The currency of the customs value. |
| Entry number | entryNumber |
Text | |
| Entry date | entryDate |
Date |
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 |
| Created | created |
Yes or no |
| Sample | sample |
Yes or no |
| Exit | Port | Notes |
|---|---|---|
| Created | created |
|
| Existing | existing |