StatusActionsUrl < Cargooffice

---+!! 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
#
# file data after this line:
fileData=
<?xml version="1.0" encoding="UTF-8"?>
{shipmentID},{lastStatus}
{orderReference},{pickupName}
<deliveryName>{deliveryName}</deliveryName></verbatim>

*NOTE:* 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 cantact 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 pre-made spreadsheet.<br /> It allows pricing, create invoices, create management information, create graphs, files for bookkeeping etc.<br /> Since most people know how to create spreadsheets and how to make calculations, this function expands the system with virtual unlimited possibilities.

To feed the spreadsheet with data from the system use the {fieldName} format in the cells where you need the information.

This action starts the spreadsheet and the result is either saved into a new spreadsheet (management info), saved into a .pdf file (invoices), saved into a .csv file (bookkeeping) or added to the order (pricing).

The spreadsheet must be in .ods format (use 'save as Open Document Spreadsheet') and uploaded to the users data directory: /data/office/spreadSheetName.ods (you need FTP access, ask us if you don't have it already).

Results will be added to shipment as following: result1=A1 to calcPrice -&gt; first action: picking up data from spreadsheet from cell A1 and feeding it to order as calcPrice result2=B1 to fuelPrice -&gt; second action: picking up data from cell B1 and saving as fuelPrice

*emailWarningsTo*

CargoOffice Administrator is able to use function: emailWarningsTo. It helps developing and fine tuning of an action. With parameter ALL [emailWarningsTo=developer@cargooffice.com:ALL] everything will be emailed to developer , without [emailWarningsTo=developer@cargooffice.com] only warnings and errors will be given to.

*Parameter :NUM*

This can be attached at the end of the result. This means that we expect result to be numeric, it is common that while spreadsheet calculation crashed output will be an open office info that our action will accept as correct one ,NUM parameter will inform developer about occurrence of such a problem [result1=A1 to calcPrice:NUM].

*Action example:*

<verbatim>
Action name   : calcPrice
Action type   : Url
Address       : http://cargotools/spreadsheet/spreadsheet.php
POST-data     :

# CN, shipmentID, sheetName and result(s) are mandatory:
CN={CN}
shipmentID={shipmentID}
emailWarningsTo=dariusz@loginet.nl:ALL

# scheet name
sheetName=spreadSheetName.ods

# feed the result(s) back into the order
result1=A1 to calcPrice:NUM
result2=B1 to fuelCost</verbatim>

---++ 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>

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

---++ 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
This topic: Cargooffice > AboutFreecargo > FreightExchangeHowto > WebHome > ShipmentStatus > StatusactionsEditScreen > StatusActionsUrl
Topic revision: r53 - 2020-12-18 - WiljoVanLenthe