(r60) StatusActionsUrl < Cargooffice

Tags: view all tags
---+!! Examples of URL Status Actions

<br />%TOC%

---++ Default statuscodes

For an overview of default statuscodes please read [[StatuscodesDefault][this]] page.
---++ External webservice call

This example status action calls an external URL, in this case to pass status information.

*Action example:*

<verbatim>
Action name   : passStatus
Action type   : Url
Address       : http://www.customer.com/shippingmanager.php?action=updatestatus
POST-data     :
order={orderReference}
status={status}
remarks={remarks}</verbatim>

Please note that this webservice call will only work for http addresses, not for https addresses.

---++ Write data to a file

This status action calls a URL to write data from a shipment into a file.<br /> The file is written into the carrier's directory structure for download by (for instance) ftp.<br /> Add directory 'in' to the file name if the carrier wants to download the file (see example below).<br /> Add directory '{customerID}/in' to the file name if a carrier's customer wants to download the file.

*Action example:*

<verbatim>
Action name   : makeFile
Action type   : Url
Address       : http://demo.cargooffice.com/ttbox/ttactionscripts/doAction.php
POST-data     :
#
# CN and shipmentID are mandatory:
CN={CN}
shipmentID={shipmentID}
#
# the name of the function to call:
action=makeFile
#
# path and name of the file to create:
file=in/status_{orderID}_{unique}.xml
#
# encoding of the output file
#encoding=UTF-8
#
# file data after this line:
fileData=
<?xml version="1.0" encoding="UTF-8"?>
{shipmentID},{lastStatus}
{orderReference},{pickupName}
<deliveryName>{deliveryName}</deliveryName></verbatim>

*NOTE1:* Illegal characters in xml tags like '<', '>', '&' and quotes are translated automatically into <verbatim>&lt; &gt; &amp; &quot; and &apos;</verbatim>
*NOTE2:* If you do want illegal characters in the content of an xml tag, for instance another xml snippet, you need to escape these characters by a backslash. For instance \>, \< or \&. <br><br>
*NOTE3:* Also see the paragraph on [[#Iterations][iterations]] below.

---++ Send BOL (Bill Of Lading) to an email address

This status action sends an email containing the BOL (Bill Of Lading) to an email address.<br /> This is similar to the order copy which is sent after entering an order (sentordercopy).

*Action example:*

<verbatim>
Action name   : mailBol
Action type   : Url
Address       : http://demo.cargooffice.com/orderbox/mailBol.php
POST-data     :
# CN and shipmentID are mandatory:
CN={CN}
shipmentID={shipmentID}
#
# to email address:
to={pickupEmail}
#
# from email address:
from=noreply@demo.com
#
# email subject:
subject=BOL for shipment {shipmentID}</verbatim>

---++ Send BOL (Bill Of Lading) as PDF to an email address

This status action sends an email containing the BOL (Bill Of Lading) as PDF to an email address.<br /> This is similar to the mailBol-action.

*Action example:*

<verbatim>
Action name   : mailBolPDF
Action type   : Url
Address       : http://demo.cargooffice.com/orderbox/mailBolPDF.php
POST-data     :
# CN and shipmentID are mandatory:
CN={CN}
shipmentID={shipmentID}
#
# to email address:
to={pickupEmail}
#
# from email address:
from=noreply@demo.com
#
# email subject:
subject=BOL for shipment {shipmentID}</verbatim>

---++ Send shipment + POD details as PDF to an email address

This status action sends an email containing shipment details plus any POD signatures or scans as PDF to an email address.

*Action example:*

<verbatim>
Action name   : mailShipmentPOD
Action type   : Url
Address       : http://demo.cargooffice.com/ttbox/mailShipmentPOD.php
POST-data     :
# CN and shipmentID are mandatory:
CN={CN}
shipmentID={shipmentID}
#
# to email address:
to={orderEmail}
#
# from email address:
from=noreply@demo.com
#
# email subject:
subject=booking details of shipment {shipmentID} ({orderReference})
#
# email txt subject (optional)
txtTemplate=shipmentPODmail.txt</verbatim>

The 'txtTemplate' must be uploaded to the carriers /data/templates folder.
---++ Puts BOL (Bill Of Lading) in ftpoutspool of carrier directory

This status action puts the BOL (Bill Of Lading) in the carrier directory.

*Action example:*

<pre>Action name   : mailBol
Action type   : Url
Address       : http://demo.cargooffice.com/orderbox/ftpBol.php
POST-data     :</pre> <div id="_mcePaste">CN= {CN}</div> <div id="_mcePaste">shipmentID= {shipmentID}</div> <div id="_mcePaste">customerID= {customerID}</div> <div id="_mcePaste">fileNameTemplate= CO_{shipmentID}_{customerID}</div>

---++ Copy POD file to a customer directory

This status action copies (or moves) a POD to a customer directory for download.

*Action example:*

<verbatim>
Action name   : copyPOD
Action type   : Url
Address       : http://demo.cargooffice.com/ttbox/ttactionscripts/movepodfile.php
POST-data     :
# either CN of trackingnbr is mandatory:
CN={CN}
trackingnbr={trackingNbr}
#
# pickup file:
pickupfile=data/signatures/{orderReference}.pdf
#
# destination file:
destinationfile=customer/in/{shipmentID}.pdf
#
# remove pickupfile yes or no:
removePickupfile=no
#
# status change on success / fail (optional)
#statusSuccess=_copyPODsuccess
#statusFail=_copyPODfail</verbatim>

*NOTE1:* you can use wildcard .* in pickupfile and destinationfile (like : data/signatures/{orderReference}.*.pdf).<br /> *NOTE2:* the status change is optional. Remove the # if you want to change the status of trackingnbr after the copy action).

---++ Send CMR to an email address

This status action sends an email containing the CMR to an email address.

*Action example:*

<verbatim>
Action name   : mailCMR
Action type   : Url
Address       : http://demo.cargooffice.com/orderbox/mailCmr.php
POST-data     :
# CN and shipmentID are mandatory:
CN={CN}
shipmentID={shipmentID}
#
# to email address:
to={orderEmail}
#
# from email address:
from=noreply@demo.com
#
# email subject:
subject=CMR for shipment {shipmentID}</verbatim>

---++ Copy a shipment to another Cargooffice

This status action sends a copy of a shipment to another carrier who also uses Cargooffice.<br /> *If the other carrier does not use Cargooffice, look below under 'Send a shipment to a subcontractor'* <br /> Normally all available data is copied to the subcontractor. However, specific fields can be translated or blanked (see example below).<br />Also, a parameter with include and/or exclude fields may be given (see below for an example).<br />Please also note these fields: refCustomerID, refShipmentID, refTrackingNbr. The subcontractor needs these fields to report statusses back.

*Action example:*

<verbatim>
Action name   : copy2subcon
Action type   : Url
Address       : http://demo.cargooffice.com/orderbox/orderCopy.php
POST-data     :
# CN and shipmentID of the sending party:
sourceCN={CN}
shipmentID={shipmentID}
#
# CN of the subcontractor:
targetCN=12021
#
# Translations and settings required by the subcontractor:
orderID={CN}{orderID}
customerID=1234
refCustomerID={customerID}
refShipmentID={orderID}
refTrackingNbr={trackingNbr}
quantity=eval({quantity}*100)
goodsID=eval(('{quantity}') ? 'centimeters' : '')
status={statusDate} {statusTime} batchentry</verbatim>

&lt;/verbatim&gt;

*NOTE :* you can only use *batchentry* or *orderentry* for the status. Any other status might lead to unpredictable results at the receivers end... *batchentry* will cause the shipment to remain in the receivers Cargooffice (as with normal batch shipments. *orderentry* will cause the shipment to be directly create an orderoutput in the receiving Cargooffice. Status *stdedibulk* will NOT create an orderoutput on the other end!!

*Same example but now with a parameter (see last line):

<verbatim>
Action name   : copy2subcon
Action type   : Url
Address       : http://demo.cargooffice.com/orderbox/orderCopy.php
POST-data     :
# CN and shipmentID of the sending party:
sourceCN={CN}
shipmentID={shipmentID}
#
# CN of the subcontractor:
targetCN=12021
#
# Translations and settings required by the subcontractor:
orderID={CN}{orderID}
customerID=1234
refCustomerID={customerID}
refShipmentID={orderID}
refTrackingNbr={trackingNbr}
status={statusDate} {statusTime} batchentry
paramID=orderCopyFields</verbatim>

*The parameter*

The parameter (in the example above 'orderCopyFields') must be created first and contain at least two lines:<br /> A line containg 'Include:'<br /> And a line containing 'Exclude:'

*Example of a parameter:*

<verbatim>
Include:
All

Exclude:
orderName
orderAddress
orderPostcode
orderCity</verbatim>

*Another example of this parameter:*

<verbatim>
Exclude:
All

Include:
pickupName
pickupAddress
pickupDate
pickupTime
deliveryName
deliveryAddress
deliveryDate
deliveryTime
quantity
packing
goodsID
weight
..</verbatim>

*NOTE:* charge- and cost-fields are never copied, unless you specify these fields under the *include* part.<br /><b>NOTE2</b>: in the Exclude section you can also use a regular expression, for example:<br /> */^pickup.*/* (excludes all pickup... fields)<br /> */^packing[2-9]|\d\d/* (excludes all packing{n} fields except packing1)

*NOTE3:* it is possible to set the targetCN to the same value as the sourceCN, effectively creating a copy of the shipment in the same Cargooffice. The fields in the copied order can be set as described above.

IF the status of the NEW shipment is set to the same as the status used to trigger this ordercopy, the action will be refused as you will create a loop that will create an indefinite number of shipments.
---++ Send a shipment to a subcontractor

This status action sends a copy of a shipment to another carrier.<br /> This example sends a CSV file, please contact us for other formats.

   * To send a CSV file, first make a copy of parameter 'CSVoutputfields' (Backoffice -&gt; Settings -&gt; Parameters).
   * Name the new parameter for example 'CSVsubcon' (use the name of the subcontractor in stead of 'subcon').
   * Also, enter the name of the subcontractor in field 'Customer' when creating the new parameter.
   * Then create an action like the example below (again, use the name of the subcontractor in stead of 'subcon'):
*Action example:*

<verbatim>
Action name   : send2subcon
Action type   : Url
Address       : http://demo.cargooffice.com/orderbox/orderOutput.php
POST-data     :
# CN and shipmentID are mandatory:
CN={CN}
shipmentID={shipmentID}
#
# The type of output:
orderOutputType=CSV
#
# The name of the new CSVsubcon parameter:
paramID=CSVsubcon
#
# The name of the subcontractor that you put in parameter field 'Customer':
customerID=subcon
#
# The email address where the CSV file must be send to:
# (multiple email addresses may be used, use comma as delimiter)
toAddress=planning@subcon.com</verbatim>

---++ Mail job list to a subcontractor

This status action sends a job list (the trip) to a subcontractor.

*Action example:*

<verbatim>
Action name   : mailJoblist
Action type   : Url
Address       : http://demo.cargooffice.com/dispatchboxv4_current/joblist2.php
POST-data     :
# CN and shipmentID are mandatory:
CN={CN}
shipmentID={shipmentID}
#
# Email address of the assigned subcontractor:
to={deliveryNodeAddress},mymailaddress@mycompany.com
#
# From email address:
from=noreply@cargooffice.com
#
# Email subject:
subject=Joblist {deliveryTripID}</verbatim>

---++ Send trip details to a subcontractor (file)

This status action sends the trip details in a file to a subcontractor.

*NOTE* This is a *trip status action*. Please read the section about [[TripStatuses][trip statuses and actions]].

*Action example:*

<verbatim>
Action name   : trip2subcon
Action type   : Url
Address       : http://demo.cargooffice.com/dispatchboxv4_current/tripOutput.php
POST-data     :
# CN and trip are mandatory:
CN={trip.CN}
tripID={trip.tripID}

# the email address where the trip details should go to
toAddress=somebody@somecompany.com

# the email subject (optional)
#subject={trip.tripID}

# the output type (optional, do not change)
#tripOutputType=tripOutputXML</verbatim>

---++ Spreadsheet call

This status action calls a spreadsheet to make calculations.<br />For instance to make calculations for pricing, volume or loadmeters and feed the results back into the shipment.

To feed the spreadsheet with data from a shipment use the format: cell(A1)={fieldName}. See the example below.

To capture results from the spreadsheet back into the shipment use the format (example): chargeAmount=cell(A2). See the example below.

The spreadsheet must be uploaded to the users data directory: /data/sheets/ (you need FTP access, ask us if you don't have it already).

*Action example:*

<verbatim>
Action name   : calcLoadmeters
Action type   : Url
Address       : http://demo.cargooffice.com/ttbox/ttactionscripts/sheet.php
POST-data     :

# CN and shipmentID are mandatory:
CN={CN}
shipmentID={shipmentID}
#
# the spreadsheet to use (must be uploaded to directory data/sheets)
sheetname=bundles.xlsx
#
# fill these cells with content from the shipment
cell(C2)={goodsID}
cell(C3)={quantity}
cell(C4)=literal
#
# copy the result cells back into the shipment:
loadmeters=cell(C4)
usedQuantity=cell(C3)
sheetused=literal</verbatim>

*Note1* This function uses open source spreadsheet calculators. It can use .xls and .xlsx files but complex Excel formulas sometimes give undefined results. Start with simple formulas in your spreadsheet and add complexity as you go. Change one formula at the time and check the result. If you get stuck please use the bugtracking system to ask us to help you with this.

*Note2* This function is available under our fair-use policy. We assume a fair-use policy of 7 statuses updates per order. If there are structurally more than 7 statuses updates per order, we will quote an additional monthly amount. The number of status updates is visible in: BackOffice -&gt; Settings and management -&gt; CargoOffice Reporting.

*Note3* If you use your spreadsheet for pricing and you need the distance in km in your calculation, we charge you EUR 0,01 per query. Normally we use Google Maps for the distance, but we can also use other providers. However, some of them are ridiculously expensive and we can't avoid to charge a different price.

---++ Update shipment

This status action updates a shipment.<br /> In the example below two extra fields are added to the shipment and filled by a substring from the status field.

*Action example:*

<verbatim>
Action name   : setETA
Action type   : Url
Address       : http://demo.cargooffice.com/ttbox/ttactionscripts/doAction.php
POST-data     :
#
# CN and shipmentID are mandatory:
CN={CN}
shipmentID={shipmentID}
#
# the name of the function to call:
action=updateShipment
#
# update or add these fields in the shipment:
freightCost=eval(round({freightCost}-{freightTax},2))
deliveryDateEst={status,33,10}
deliveryTimeEst={status,44,5}</verbatim>

The first character of a string is character# 0. Should you need the first 2 characters of a string, then you would need to put {variable,0,2}.

*Not eval (!eval)* If you place an exclamation mark before eval (!eval) and the evaluated result is blank, then the field is not created or updated.

Possible options for using this in actions:
   * quantity2=!eval({quantitySub2}) =&gt; only if quantitySub2 is set, quantity2 will be filled
   * packing2=!eval({packingSub2}) =&gt; also works for non-numeric values
   * packingSub1=!eval({packing1:xlat:pallet=PAL,Koker=KOK}) =&gt; you can include xlat or regex functions
---++ Update trip

This status action updates a trip.

*Action example:*

<verbatim>
Action name    : updateTrip
Action type    : URL
Address        : http://loginet.cargooffice.com/ttbox/ttactionscripts/doAction.php
POST-data      : 
#
CN and tripID are mandatory:
CN={trip.CN}
tripID={trip.tripID}
#
# the name of the function to call:
action=updateTrip
#
# update these fields in the trip:
startTime={statusTime}
status=+{statusDate} {statusTime} {statusClean}</verbatim>

---++ Set Status

This updates the status of a shipment at a certain date and time or after a certain delay.<br /> In the example below the delay of 120 minutes supersedes the date and time setting.

*Action example:*

<verbatim>
Action name   : setStatus
Action type   : Url
Address       : http://demo.cargooffice.com/ttbox/ttactionscripts/doAction.php
POST-data     :
#
# CN and shipmentID are mandatory:
CN={CN}
shipmentID={shipmentID}

# the name of the function to call:
action=setStatus

# the new status for the shipment:
status=_sendNotification

# (optional) the date of the new status:
date=2012-09-18

# (optional) the time of the new status:
time=15:10

# (optional) a delay in minutes before the status must be set
# (supersedes the date and time setting)
delay=120

# (optional) a condition that must be true at execution time
# note: database variables between [], e.g. [shipmentID]
condition=[pickupName] = "Maersk Terminal Rotterdam"</verbatim>

*Condition examples:*

<verbatim>
[customerID] = 12345
[volume] >= 40 
[weight] < 100 
[pickupName] = "Maersk Terminal Rotterdam"
[status] = /delayed/i (regular expression)
[status] != /delivered/i (regular expression)
[statusHist] != /Begin\sladen|Vertrek\slaadadres|laden\swerkelijk/ (regular expression with 3 values)
Please note that in the last example, the spaces are escaped with \s and different values are seperated by |.</verbatim>

*Valid operators:*

<verbatim>
=
>
<
>=
<=
!=</verbatim>

*Regular expresions:*

The regular expression format (last two examples above) is meant for more experienced users, for example programmers who know what [[http://en.wikipedia.org/wiki/Regular_expression][regular expressions are, more specific ]] [[http://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions][perl compatible regular expressions]] [[http://en.wikipedia.org/wiki/Regular_expression][. ]]

---++ Set Time Frame

Transform an ETA time into a time window.<br /> Example: 08:19 is transformed into 07:30 till 09:30 (a time window of 2 hours).<br /> This time window can be used to inform parties about the expected delivery time (or about a change in the expected delivery time).

The program uses field *deliveryTimeEst* (the ETA time) that must already be present in the shipment data (mind the capital letters in this field name).<br /> This field can be uploaded via an EDI message or set by an earlier status action like : [[StatusActionsUrl#Update_shipment][Update_shipment]].<br /> Optionally field *deliveryDateEst* is used for the date, otherwise the existing field *deliveryDate* is used.

Three extra fields are created in the shipment data; *planneddate*, *plannedtimefrom* and *plannedtimeto*.<br /> These fields can be used to inform parties about a (new) time window, like: "The new ETA for your delivery is {plannedtimefrom} - {planneddateto}".<br /> To facilitate this, the program changes the status of the shipment into *_timeframeset (hh:mm - hh:mm)* or (optional) to a status given in the POST-data.

Whenever a new statusupdate is received that triggers this action, the optional deliveryDateEst and (possibly updated) deliveryTimeEst value are first compared with the existing planneddate and plannedtimefrom/plannedtimeto.

If deliveryDateEst is different then planneddate a new time window is calculated.

If deliveryTimeEst falls outside the window defined by plannedtimefrom-plannedtimeto a new window is calculated.

After calculating a new time window, the status _timeframeset or another status that has been defined will be set. This new status can be used to send emails or sms messages having similar content.

If the new deliveryTimeEst falls within the originally calculated window, no new window is calculated and no status is set and hence no further actions are taken.

*Action example:*

<verbatim>
Action name   : maketimeframe
Action type   : Url
Address       : http://demo.cargooffice.com/ttbox/ttactionscripts/maketimeframe.php
POST-data     :
#
# CN and shipmentID are mandatory:
CN={CN}
shipmentID={shipmentID}

# (optional) the new status for the shipment:
#status=_timeframeset
# Note: when using date or time fields: use square brackets in stead of curly brackets.
status=Estimated delivery time ([plannedtimefrom] - [plannedtimeto])</verbatim>

*Note1* This function needs to be specifically implemented for your cargooffice, so please contact us before you create an action like this.

*Note2* This function is available under our fair-use policy. We assume a fair-use policy of 7 statuses updates per order. If there are structurally more than 7 statuses updates per order, we will quote an additional monthly amount. The number of status updates is visible in: BackOffice -&gt; Settings and management -&gt; CargoOffice Reporting

---++ Iterations

Sometimes you want *iterations* in your template, for example to iterate an output line for each goods line.<br /> There are two types of iterations, one for goods lines and one for files (documents, PODs, Bill of Lading) etc.

Below are two examples of a makeFile template:

*Example 1* (iterate for each goods line):<br /> *NOTE:* you must include the *&lt;!-- iterate --&gt;* and *&lt;!-- end iterate --&gt;* lines around the part to iterate. They will not be included in the output.

<verbatim>
Action name   : makeFile
Action type   : Url
Address       : http://demo.cargooffice.com/ttbox/ttactionscripts/doAction.php
POST-data     :
#
# CN and shipmentID are mandatory:
CN={CN}
shipmentID={shipmentID}
#
# the name of the function to call:
action=makeFile
#
# path and name of the file to create:
file=123456/in/{orderReference}-{customerID}TEST.xml
#
# file data after this line:
fileData=
<?xml version="1.0" encoding="UTF-8"?>
<xmlEdi>
  <transportOrders>
    <transportOrder>
      <customerID>{customerID}</customerID>
      <orderReference>{orderReference}</orderReference>
      <pickupName>{pickupName}</pickupName>
       <pickupAddress>{pickupAddress}</pickupAddress>
       <deliveryName>{deliveryName}</deliveryName>
       <deliveryAddress>{deliveryAddress}</deliveryAddress>
       <goodsLines>
<!-- iterate -->
         <goodsLine>
           <quantity>{quantity1}</quantity>
           <goodsID>{goodsID1}</goodsID>
           <weight>{weight1}</weight>
         </goodsLine>
<!-- end iterate -->
       </goodsLines>
    </transportOrder>
  </transportOrders>
</xmlEdi></verbatim>

*Example 2* (iterate for each file):<br /> *NOTE1:* you must include the *&lt;!-- include file --&gt;* and *&lt;!-- end include file --&gt;* lines around the part to iterate. They will not be included in the output.<br /> *NOTE2:* the {filecontent} will be base64 encoded.

<verbatim>
Action name   : makeFile
Action type   : Url
Address       : http://demo.cargooffice.com/ttbox/ttactionscripts/doAction.php
POST-data     :
#
# CN and shipmentID are mandatory:
CN={CN}
shipmentID={shipmentID}
#
# the name of the function to call:
action=makeFile
#
# path and name of the file to create:
file=in/status_{orderID}_{unique}.xml
#
# file data after this line:
fileData=
<?xml version="1.0" encoding="UTF-8"?>
<statusReport>
  <order>{orderReference}</order>
  <pickupName>{pickupName}</pickupName>
  <files>
<!-- include file /data/signatures/{shipmentID}*.* -->
    <file>
      <filename>{filename}</filename>
      <filecontent>{filecontent}</filecontent>
  </file>
<!-- end include file -->
  </files>
  <status>{lastStatus}</status>
</statusReport></verbatim>

<br /><br /> -- Main.HenkRoelofs - 2012-05-09
Topic revision: r60 - 2021-09-03 - HenkRoelofs
~~Edit~~
~~Attach~~