You may use this web service to retrieve report data from the Fleettracker database. This section describes the concept of this service.
- WSDL file: WSAPIReport.wsdl
- Implementation: WSAPIReport.php
Operation GetReportTable
The operation allows to retrieve report data in form of a table structure.
The client has to fill out the GetReportTableRequestData structure to specify the report data that have to re retrieved. the response is made of a table containing the result of the request. Each row represents one report (revision) the user has entered at a given time.
Request data structure GetReportTableRequestData
You will find the definition of the request data in the WSDL file.
<?xml version="1.0" encoding="UTF-8"?> <xsd:complexType name="GetReportTableRequestData"> <xsd:sequence> <xsd:element name="apiIdentifier" type="api:APIIdentifier" minOccurs="1" maxOccurs="1"> <xsd:annotation> <xsd:documentation> The reporting or requesting party. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="shipRequestFilter" type="tns:ShipRequestFilter" minOccurs="0" maxOccurs="1"> <xsd:annotation> <xsd:documentation>The list of ships we may want to see. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="timeFrameRequestFilter" type="tns:TimeFrameRequestFilter" minOccurs="0" maxOccurs="1"> <xsd:annotation> <xsd:documentation>The optional time frame. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="maxCount" type="xsd:int" minOccurs="0" maxOccurs="1"> <xsd:annotation> <xsd:documentation>Do not return more than the maxCount reports. Set this to 0 for all reports. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="columnHeadersOnly" type="xsd:boolean" minOccurs="0" maxOccurs="1" default="false"> <xsd:annotation> <xsd:documentation>Do only return column headers. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="ffTemplateName" type="xsd:string" minOccurs="0" maxOccurs="1"> <xsd:annotation> <xsd:documentation>This is the Fleetform form template name (see FolderTemplate.Template.TemplateName). You have to either set this or ffTableName. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="ffFolderTemplateTypeTag" type="xsd:string" minOccurs="0" maxOccurs="1"> <xsd:annotation> <xsd:documentation>This is the Fleetform folder template typeTag, e.g. CREWLIST, PERFORMANCEREPORT, SHIPDETAILS, etc. See FolderTemplate in fleetform.xsd for possible values. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="ffTableName" type="xsd:string" minOccurs="0" maxOccurs="1"> <xsd:annotation> <xsd:documentation>This is the optional name of a table within a form. For example, the crewlist form template contains a table. If you set this value, the values of the given table are evaluated instead of the mere input widgets. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="ffFolderTemplateGUID" type="xsd:string" minOccurs="0" maxOccurs="1"> <xsd:annotation> <xsd:documentation>This is the Fleetform folder template GUID. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="sortValuesBy" type="tns:ValueSorting" minOccurs="0" maxOccurs="1" default="TIMESTAMP_DESC"> <xsd:annotation> <xsd:documentation>Optional sorting of values. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="includeShipDetails" type="xsd:boolean" minOccurs="0" maxOccurs="1" default="false"> <xsd:annotation> <xsd:documentation>Set this to true if you want to include ship details in each row. </xsd:documentation> </xsd:annotation> </xsd:element> </xsd:sequence> </xsd:complexType>
The apiIdentifier has to contains the valid GUIDs for accessing the data. Otherwise, the service returns an error message. You can only request information of ships belonging to your particular GUID.
The shipRequestFilter may contain a set of IMO numbers of the ships you want to retrieve information about. At least one IMO number has to be provided with this filter.
The timeFrameRequestFilter defines the time period for which the data will be retrieved. Please note that we use UTC for timestamps.
The maxCount parameter indicates a maximum limit how many report rows should be returned. Set this to '0' to disable this restriction.
If the columnHeadersOnly flag is set to 'true' then only the column headers are returned.
The ffTemplateName may be set to identify the report name, e.g. 'ArrivalReport'. An alternative is the ffFolderTemplateTypeTag which indicates particular report types like CREWLIST, PERFORMANCEREPORT or SHIPDETAILS. also, you can use the ffFolderTemplateGUID to identify a template by its unique GUID.
If you want to retrieve data from a table that is part of a form template, use ffTableName to identify the table name.
The sortValuesBy parameter may be set to TIMESTAMP_DESC or TIMESTAMP_ASC (the default).
If you set includeShipDetails to 'true', each row will contain some basic ship details information like the ship name and the IMO number.
Response data structure GetReportTableResponseData
The operation returns a response containing the result of the request. The following listing shows some important parameters.
<?xml version="1.0" encoding="UTF-8"?>
<xsd:complexType name="GetReportTableResponseData">
<xsd:sequence>
:
:
<xsd:element name="columnHeaders" type="tns:ColumnHeader" minOccurs="0" maxOccurs="unbounded">
<xsd:annotation>
<xsd:documentation>
The set of widgets containing the table header
information of the different revision values.
This set contains
all widgets referenced by the revisions.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="rowDataSet" type="tns:RowDataSet"
minOccurs="0" maxOccurs="unbounded">
<xsd:annotation>
<xsd:documentation>
The set of row datasets containing the data.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
:
</xsd:sequence>
</xsd:complexType>
The columnHeaders array contains information about the column headers the table is made of. Each column header represents an entry field in a form the user has filled out.
The rowDataSet is an array of zero or more 'rows' containing the data records. Each row contains zero or more cells representing a single data entry.
ColumnHeader
A column header actually represents a data type. Each cell value is associated with a column header by means of the column name. In addition, each column header has a description and a unit. The widgetValueType is an integer value defining the simple type of the value.
<?xml version="1.0" encoding="UTF-8"?>
<xsd:complexType name="ColumnHeader">
<xsd:annotation>
<xsd:documentation>This is a column header. Note that we may
have a
reference to a widget but for DR2 data we do not.
</xsd:documentation>
</xsd:annotation>
<xsd:sequence>
<xsd:element name="name" type="xsd:string" minOccurs="1"
maxOccurs="1">
<xsd:annotation>
<xsd:documentation>The unique column name. Identify the values by
this name.
If this column is a formula column, then the name is
the appropriate result variable name that the formula has
calculated.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="description" type="xsd:string"
minOccurs="1" maxOccurs="1">
<xsd:annotation>
<xsd:documentation>The column description
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="unit" type="xsd:string" minOccurs="0"
maxOccurs="1">
<xsd:annotation>
<xsd:documentation>The optional unit
</xsd:documentation>
</xsd:annotation>
</xsd:element>
:
<xsd:element name="widgetValueType" type="xsd:int"
minOccurs="0" maxOccurs="1" default="0">
<xsd:annotation>
<xsd:documentation>The widget value type. So far we are using an
integer index indicating the
type. See fleetform.xsd and
documentation for details.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
:
</xsd:sequence>
RowDataset
Each row dataset has a timestamp in UTC indicating when the data were entered and last modified. The additional firstRevisionTimestamp is the timestamp when the record has been created the first time. The 'row number is indicating the table row if the request addresses a table within a form.
The author is the name of the person who entered the report. The ship details is an optional record containing the name and IMO number of the vessel on which the record was originated.
The dataset array is a set of cells containing the row values. Please note that not each row may contain a complete set of cell entries according to the column headers.
The relatedDestination is the optional destination belonging to this row. Only set for arrival and departure reports.The nextDestination is the optional next destination. For arrival and departure reports, this entry is set to the destination FOLLOWING the related destination. For all other reports, this entry is the NEXT destination (coming up).
<?xml version="1.0" encoding="UTF-8"?> <xsd:complexType name="RowDataSet"> <xsd:annotation> <xsd:documentation>This is a row of the table. it contains the datasets of one row. </xsd:documentation> </xsd:annotation> <xsd:sequence> <xsd:element name="timestamp" type="xsd:dateTime" minOccurs="1" maxOccurs="1"> <xsd:annotation> <xsd:documentation>The timestamp (revision timestamp for fleetform, else the timestamp of the report entry). </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="firstRevisionTimestamp" type="xsd:dateTime" minOccurs="0" maxOccurs="1"> <xsd:annotation> <xsd:documentation>The timestamp of the first (oldest) revision. Note that this maybe NULL. It is equal to the timestamp if we have one revision only. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="rowNo" type="xsd:int" minOccurs="0" maxOccurs="1"> <xsd:annotation> <xsd:documentation>The optional row number. This is set if we have a table. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="author" type="xsd:string" minOccurs="0" maxOccurs="1"> <xsd:annotation> <xsd:documentation>The author </xsd:documentation> </xsd:annotation> </xsd:element> : <xsd:element name="shipDetails" type="api:FleettrackerShip" minOccurs="0" maxOccurs="1"> <xsd:annotation> <xsd:documentation>The ship object belonging to this dataset. Please note that we only fill some values like name, charterShipName and IMO number. This object is only set if the includeShipDetails flag is set to true. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="datasets" type="tns:CellDataSet" minOccurs="0" maxOccurs="unbounded"> <xsd:annotation> <xsd:documentation>The cell datasets of this row. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="relatedDestination" type="tns:DestinationEntry" minOccurs="0" maxOccurs="1"> <xsd:annotation> <xsd:documentation> This is the optional destination belonging to this row. Only set for arrival and departure reports. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="nextDestination" type="tns:DestinationEntry" minOccurs="0" maxOccurs="1"> <xsd:annotation> <xsd:documentation> This is the optional next destination. For arrival and departure reports, this entry is set to the destination FOLLOWING the related destination. For all other reports, this entry is the NEXT destination (coming up). </xsd:documentation> </xsd:annotation> </xsd:element> </xsd:sequence> </xsd:complexType>
CellDataset
Each cell contains a single value entity. Please note that the value is always a string type. Numeric values are represented in mere US float or integer notation. The optional unit is overriding the unit field of the related column header and contains the physical unit name.
The columnname is the reference to the column header object. The widget_id is the Fleetform widget id as defined by the form template. It indicates the widget that was used to enter the value.
<?xml version="1.0" encoding="UTF-8"?> <xsd:complexType name="CellDataSet"> <xsd:annotation> <xsd:documentation>This is a data entry in a cell of a row of the table. </xsd:documentation> </xsd:annotation> <xsd:sequence> <xsd:element name="value" type="xsd:string" minOccurs="1" maxOccurs="1"> <xsd:annotation> <xsd:documentation>The value </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="unit" type="xsd:string" minOccurs="0" maxOccurs="1"> <xsd:annotation> <xsd:documentation>The optional unit </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="columnname" type="xsd:string" minOccurs="1" maxOccurs="1"> <xsd:annotation> <xsd:documentation>The column name this cell belongs to. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="widget_id" type="xsd:int" minOccurs="0" maxOccurs="1"> <xsd:annotation> <xsd:documentation>The widget id these values belongs to. Note that this entry is optional and may be null. Also, this is NOT the database id of the widget! </xsd:documentation> </xsd:annotation> </xsd:element> </xsd:sequence> </xsd:complexType>