OCIMF
SIRE Web Services 2.0
29 October 2010
v1.0.01
Introduction
OCIMF SIRE Web Services V2 are available at the following URL:
http://wsv2.ocimf-sire.com/OcimfServices.asmx
The client demonstrator is available here:
http://ocimf-dev-1.com/wsclient/
This document describes the process to integrate with the OCIMF Sire Web Services
v2.0. The web services v2.0 framework has the following key features:





Common web services interface to all OCIMF applications
A service session is created to authenticate a client across multiple service
calls
A single point of invocation is provided to route all service calls through a
common endpoint
A single response document is common across all service methods
Revision control of service method interfaces
System scope
The OCIMF Web Services v2.0 system currently covers Sire v4 inspections and
particulars as well as Sire v5 inspections.
OVID inspections and particulars are also available through this service. This
documentation will be merged.
The crew web services will be made available in v2.0 with the same I/O as version
1.11.
Workflow
The workflow to integrate with the OCIMF web services v2.0 interface is:




Call “StartWebServiceSession” to authenticate the client against a session
The session response, upon success, is a key string to identify the user during
the session
Call “InvokeMethod” for each service method required during the session
passing:
o Key string – session ID
o The method name required
o The version of the method
o The request XML
The service’s response XML will be returned
The Web Services Response
All Web Services methods return a XML response in the following format:
<OcimfWsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.ocimf.com/">
<ResultCode/>
<ErrorMessage/>
<DataXml/>
<ErrorTicketNumber/>
</OcimfWsResponse>
The ResultCode (int) node enumerates the status of the request as follows:
1
OK
100 Generic error
101 Insufficient permissions
102 Invalid request schema
The request sent to the server is using an incorrect schema or there is data missing
103
150
151
200
Invalid login
Authorisation token not found
Authorisation token expired
Unsupported document type requested
A request was made for an OCIMF document type which is either not supported by Web
Services or by the specific method being requested
201
User/organisation cannot pay on account
Account purchases only (no credit card payments) can be made through Web Services. If the
authenticated user cannot purchase on account they will receive this error.
202
203
Document does not exist
Insufficient funds to purchase document
The authenticated user’s organisation does not have sufficient account funds to purchase the
document.
204
Document not authorised
The authenticated user cannot purchase the requested document, e.g. because the document
is pending publication and the user is not the submitter.
The ErrorMessage (string) node provides further detail for the response code where
appropriate.
The DataXml (escaped XML string) node provides the requested data as an escaped
XML document.
If an error occurred a ticket number will be raised and shown in the response.
Security and Authentication
Web Services requires a user to authenticate against the following method:
http://ws.ocimf-ovid.com/OcimfServices.asmx?op=StartWebServiceSession
The user must authenticate using the account, login and password credentials used
to access ocimf-ovid.com.
Authentication will, upon success, initiate a 20 minute session and return a token
which can be used throughout web services as credentials.
An unsuccessful authentication response will show the following:
<OcimfWsResponse>
<ResultCode>103</ResultCode>
<ErrorMessage/>
</OcimfWsResponse>
A successful authentication response will take the following form:
<OcimfWsResponse>
<ResultCode>1</ResultCode>
<ErrorMessage/>
<DataXml>
&lt;Token&gt;d3b3d416-b0dd-4fa0-b65a-2cef1fdc7fc9&lt;/Token&gt;
</DataXml>
</OcimfWsResponse>
When unescaped the DataXml will contain the following document:
<Token>d3b3d416-b0dd-4fa0-b65a-2cef1fdc7fc9<Token>
The authenticating user must have explicit permissions to access both Web Services
and the appropriate application (e.g. Sire) in order to successfully authenticate.
Invoking methods
Beyond the authentication step all methods are invoked from the following URL:
http://wsv2.ocimf-sire.com/OcimfServices.asmx?op=InvokeMethod
The method takes the following parameters:
TokenID
GUID
The authentication token
MethodName
String
The name of the method being requested
Shown at the top of each method description section below
Version
String
RequestXml
XML
The version of the method being requested
Shown at the top of each method description section below
The request XML specific to the method
The invoke method will return a response document conforming to the schema
identified above.
Fetching the Document Index
Method name (for invoke): SIRE.GetDocumentIndex
Current version (for invoke): 1.0
The document index method requires a request using a format as below:
<Request>
<DateCriteria type="" dateStart="" dateEnd="" year="" month="" day="" />
<DocumentCriteria includePending=""/>
<VesselCriteria name="" id="" imo="" />
</Request>
The DateCriteria node specifies the specific or range date for the documents being
requested (the inspection’s modified date). The date type can be one of the
following:
Date type
Required detail attributes
Data searched
year
@year
Modified in a given year
month
@year, @month
Modified in a given month
day
@year, @month, @day
Modified in a given day
since
@start
Modified since
range
@start, @end
Modified between
Dates must be sent in YYYY-MM-DD HH:MM:SS format.
The index can return only published documents or also pre-published depending on
the value of the @includePending attribute to the DocumentCriteria node. Booleans
must be sent as their full ‘true’ or ‘false’ string.
The request can optionally filter by vessel by supplying a VesselCriteria node with a
@name, @id or @imo attribute. The string wildcard character (for use with @name)
is %.
The following examples are valid requests:
<Request>
<DateCriteria type="day" year="2010" month="10" day="31"/>
<DocumentCriteria includePending="False"/>
</Request>
<Request>
<DateCriteria type="range" dateStart="2010-01-01 12:00:00"
dateEnd="2010-01-02 12:00:00"/>
<DocumentCriteria includePending="True"/>
</Request>
<Request>
<DateCriteria type="year" year="2010"/>
<DocumentCriteria includePending="False"/>
<VesselCriteria name="audaci%"/>
</Request>
The following shows an example of the response:
<OcimfWsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.ocimf.com/">
<ResultCode>1</ResultCode>
<ErrorMessage/>
<ErrorTicketNumber/>
<DataXml>&lt;ServiceResponse requested="2010-1031T22:57:31.970"&gt;&lt;Status code="100" message="Success" /&gt;&lt;Document
docType="4120" docKey="1000-1194-1878-0949" processStatus="303"
modified="2010-01-02T11:45:03.057"&gt;&lt;Vessel id="20012324" name="Golar
Arctic" imo="9253105" /&gt;&lt;Operator name="Wilhelmsen Ship Management
(Norway) AS" /&gt;&lt;Submitter name="BP SHIPPING" inspectionDate="2009-1213T00:00:00" /&gt;&lt;/Document&gt;&lt;Document docType="2000"
docKey="1000-1304-1879-9525" processStatus="303" modified="2010-0101T13:02:52.463"&gt;&lt;Vessel id="20025037" name="GOLD STAR" imo="" reg=""
vin="BDR-IV-00069" /&gt;&lt;Submitter name="INTERNATIONAL MARINE
TRANSPORT (IMT)" inspectionDate="2009-12-21T00:00:00"
/&gt;&lt;/Document&gt;&lt;/ServiceResponse&gt;</DataXml>
</OcimfWsResponse>
When unescaped, the DataXml shows the following document:
<ServiceResponse requested="2010-10-31T22:57:31.970">
<Status code="100" message="Success"/>
<Document docType="4120" docKey="1000-1194-1878-0949"
processStatus="303" modified="2010-01-02T11:45:03.057">
<Vessel id="20012324" name="Golar Arctic" imo="9253105"/>
<Operator name="Wilhelmsen Ship Management (Norway) AS"/>
<Submitter name="BP SHIPPING" inspectionDate="2009-1213T00:00:00"/>
</Document>
<Document docType="2000" docKey="1000-1304-1879-9525"
processStatus="303" modified="2010-01-01T13:02:52.463">
<Vessel id="20025037" name="GOLD STAR" imo="" reg="" vin="BDRIV-00069"/>
<Submitter name="INTERNATIONAL MARINE TRANSPORT (IMT)"
inspectionDate="2009-12-21T00:00:00"/>
</Document>
</ServiceResponse>
The following data is returned in the index DataXml:
 Date the index was built
 For each document found the document’s type and key is returned; these are
used to request the document itself
 The document’s process status enumerator (see below)
 The document’s modified date – the date the document’s metadata
(document contents, process status, etc.) was modified
 The vessel’s ID, name, IMO, registered number and VIN
 The operator’s name (if the vessel is explicitly linked to an operator)
 The submitting organisation’s name and the inspection date (if the document
is an inspection)
Fetching a Document’s metadata and contents
Method name (for invoke): SIRE.GetDocument
Current version (for invoke): 1.0
The document fetch method requires a request using a format as below:
<Request docType="4100" docKey="1000-1014-1874-3607" includeMetadata="True"
includeContents="True" documentFormat="TEXT/XML" approvePurchase="True"
modifiedDate="2010-10-01 12:00:00"/>
The document itself is identified using the document’s type and key which can be
found in the index.
The index’s response schema is reduced in comparison to earlier versions of Sire web
services. It is intended that consumers of the service use the GetDocument method
to fetch the extra document metadata as well as the document’s contents.
The consumer can select whether to request the metadata and/or the contents using
the @includeMetadata and @includeContents attributes.
The requested rendition formation is identified as either ‘TEXT/XML’ or
‘APPLICATION/PDF’.
The @approvePurchase attribute identifies whether a the authenticated user allows
a purchase to be logged if one is required.
In the case of PDF renditions the binary is returned as a Base64 string.
If purchase is required but @approvePurchase was not set the DocumentContents
node would be blank and an appropriate error would be thrown.
The following is an example of a response document:
<ServiceResponse requested="2010-10-31 23:11:37" docType="4100"
docKey="1000-1014-1874-3607">
<Status code="100" message="Success"/>
<DocumentMetadata docType="4100" docKey="1000-1014-1874-3607"
processStatus="303" modified="2009-12-26T11:20:58.877">
<Vessel id="20024043" name="JAG AABHA" imo="9388948"
flag="India" dwt="74868" operatingCompany="The Great Eastern Shipping Company
Ltd" latestvpqdate="2010-09-15T12:51:31" created="2008-11-05T09:09:27"
modified="2010-10-07T13:46:12"/>
<Operator name="THE GREAT EASTERN SHIPPING CO "/>
<Inspection id="213891" commentsInitial="1"
commentsSubsequent="0" inspectingCompany="BHPB PETROLEUM LTD"
inspectionDate="2009-12-09T00:00:00" operation="210" releaseDate="2009-1225T00:00:00" vesselName="JAG AABHA" operatorName="The Great Eastern
Shipping Co Ltd" created="2009-12-09T18:07:26" modified="2009-1226T11:20:49"/>
<Submitter name="BHPB PETROLEUM LTD" inspectionDate="2009-1209T00:00:00"/>
<Transaction purchased="0"/>
</DocumentMetadata>
<DocumentContents format="TEXT/XML"
isBinary="false"><![CDATA[]]></DocumentContents>
</ServiceResponse>
If @includeMetadata was selected the DocumentMetadata element will be included.
The metadata includes the following in addition to that which is returned from the
index:
 The flag, weight, operating company, latest VPQ date, created date and
modified date of the vessel
 An Inspection element returning details of the operator’s comments,
inspecting company, inspection date, operation (enumeration), release date,
inspection vessel name, inspection operator name, created date and
modified date
 A Transaction element with a Boolean @purchased attribute to identify
whether the client user has previously purchased the document
If @includeContents was selected the DocumentContents element will be included.
This element contains attributes for the MIME type and whether the response is in
binary (Base64) format. The string (XML) or binary (PDF) data is included in a CDATA
block.
Enumerators
Document status
101 Original
102 Corrected
103 Withdrawn
Operation
201 Abu Dhabi
202 At anchor
203 Ballasting
204 Bunkering
205 Deballasting
206 Discharging
207 Idle
208 In drydock
209 In transit
210 Loading
211 Repairs afloat
212 River transit
213 STS discharging
214 STS loading
299 Unclassified inspection
Processing status
301 Unprocessed
302 Pending operator comments
303 Report published
304 Inspector amended pending
305 Inspector amended published
Contact Details
Marine Information Systems Limited
1 Victoria Square
Birmingham
B1 1BD
0121 277 4900
info@marineinfosys.com
http://www.marineinfosys.com
Marine Information Systems Limited
October 2010