FishServe - Lining Event

Lining Event

The sections below describe the information necessary to create, get and update a Lining event.

**Change history**
Date	Change
01/09/2021	Released to production Implementation of circular changes for September 2021.
05/04/2019	Correction to documentation, Hook Space Metres from 'Mandatory' to 'Conditional'.
21/12/2018	Released to production
10/12/2018	Changed validation on 'Hook Space Metres' - optional for method Dahn Line - DL.
11/06/2018	Added new fields; 'Fishing Under HSP' and 'Autolining' Changed validation on 'Number of Hooks' to be Must be greater than 0 Removed reference to Non Fish Protected Species Catches - this is now a seperate event
11/09/2017	Updated the GET URL to include the Software Installation Id and Completer User Id parameters. Added Completed by Name to the Get request body.
31/08/2017	Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017	Updated Request Header to include Signature instead of Bearer Token.
21/08/2017	Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here.
20/07/2017	Attribute Hook Space Metres validation changed to allow decimal.
14/07/2017	Attribute Hook Space Cm relabelled to Hook Space Metres.
05/07/2017	Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
28/06/2017	Updated NFPS parameter field names from 'Count Injured', 'Count Uninjured' and 'Count Dead' to ''Number Injured', 'Number Uninjured' and 'Number Dead'.
16/06/2017	Trip ID field added to the API actions CREATE, GET and UPDATE. Schema Edition and Event Version fields added to the API action GET. Some field name changes. Grouping of locations and dates into Geolocation Set Parameters and Geolocation Parameters.
29/05/2017	Initial publication.

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v2/lining/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v2/lining/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

Parameter	Required	Data type	Description
Client Number	Mandatory	String	The main permit holder client number that the event is submitted against.
Event ID	Mandatory	String	Unique logbook generated ID for an event.

Request Header:

Content-Type: application/json
Signature: signature generated from the digital signature algorithm using the request body and private key.

Request Body Parameters:

Parameter	Required	Data Type	Validation and Additional Notes
Event Header	Mandatory	Event Header Set	See Event Header Properties below.
Fishing Under HSP	Optional	Boolean	The Fisher can state whether they are fishing under a High Seas Permit or not.
Fishing Method Code	Mandatory	String	Must be a valid fishing method code for the Fishing Event Type. Validated against Fishing Methods Master Data. E.g. the CP method must be reported through the potting Fishing Event.
Mitigation Device Codes	Mandatory	Array of Strings	Validated against Mitigation Devices for Fishing Methods master data.
Target Species Code	Mandatory	String	Must be a valid species. Validated against the Fish Species master data.
Integrated weight line used?	Conditional	Boolean	Must be populated if fishing method is 'BLL' or 'TL', otherwise optional.
External weight (kg)	Conditional	Number	Must be provided, and be greater than zero, if fishing method is 'BLL' or 'TL', and Integrated weight line used? is false. Must not be provided if Integrated weight line used? is true. Optional if fishing method is 'DL'.
Number of hooks per external weight	Conditional	Number
Start Location	Mandatory	Geolocation Set	See Geolocation Set Parameters below.
Is Non Fish Or Protected Species Catch Present	Mandatory	Boolean	The Fisher is to state whether or not they have caught any non-fish or protected species.
Hook Space Metres	Conditional	Number	Decimal to 2dp. Must be greater than 0. Optional if fishing method is 'DL'.
Number of Hooks	Mandatory	Number	Must be a whole number. Must be greater than 0.
Bottom Depth Metres	Mandatory	Number	Must be a whole number. Must be greater than 0.
Is Line Lost	Optional	Boolean	Records if the line has been lost and unable to be hauled.
End of Set Location	Mandatory	Geolocation Set	See Geolocation Set Parameters below. Optional if ‘Is Line Lost’ is true or fishing method is 'DL'.
Start of Haul Location	Mandatory	Geolocation Set	See Geolocation Set Parameters below. Optional if ‘Is Line Lost’ is true or fishing method is 'DL'.
Autolining	Conditional	Boolean	Must be provided if 'Fishing Methods' master data property 'require_autolining = true'. Can be provided for other Fishing Methods, ERS will not reject the event if provided.
Number of Lines Hauled	Conditional	Number	Must be provided if 'Fishing Methods' master data property 'require_lines_hauled = true'. Must be a whole number. Must be greater than 0. Can be provided for other Fishing Methods, ERS will not reject the event if provided.
Estimated Green Weight for all other Species Kg	Optional	Number	Decimal to 2dp. Must be 0 or greater.
Finish Location	Mandatory	Geolocation Set	See Geolocation Set Parameters below. Location when net(s) on deck.
Catches	Optional	Array of Catches	Can be 0 or many Catch records. Records all species caught See Catches Parameters below.

Event Header Properties:

Parameter	Required	Data Type	Validation and Additional Notes
Event ID	Mandatory	String	Unique logbook generated ID for an event. The same event ID as defined in the URL.
Trip ID	Mandatory	String
Software Vendor	Mandatory	String	Your software vendor name. For example, e-logbook.
Software Version	Mandatory	String	Your software version number. For example, 1.0.0.0
Software Installation Id	Mandatory	String	Your software installation ID. For example, a13afab2-c409-4622-b8f8-146996587809 Must be the Software Installation Id that was registered with the user and public key.
Completer User Id	Mandatory	String	The user ID retrieved from registering the logbook.
Client Number	Mandatory	String	Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used	Mandatory	Boolean	Identifies if the fishing took place on a vessel or not.
Vessel Number	Mandatory	String	Must be a valid Vessel number. Must be provided if 'Is Vessel Used' = True. Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'. If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.
Notes	Optional	String	The Fisher may record additional information relating to the event.
Completed Date Time	Conditional	String	Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update. Date 24hr + UTC offset.
Amendment Reason	Conditional	String	Must be provided for Update. Must be null for Create. ERS will not accept the event if provided for create.

Geolocation Set Parameters:

Parameter	Required	Data Type	Validation and Additional Notes
System Date Time	Mandatory	String	At least one group of system or manual Date Time parameters must be provided if line is not lost. Optional if Fishing Method is 'DL'. Date 24 hr + UTC Offset.
Manual Date Time	Optional	String
System Location	Conditional	Geolocation	At least one group of system or manual location parameters must be provided if line is not lost. Optional if Fishing Method is 'DL'. See geolocation parameters below.
Manual Location	Conditional	Geolocation

Geolocation Parameters:

Parameter	Required	Data Type	Validation and Additional Notes
Latitude	Mandatory	decimal degrees, 4dp	Minimum of 4dp required.
Longitude	Mandatory	decimal degrees, 4dp	Minimum of 4dp required.

Catches Parameters:

Parameter	Required	Data Type	Validation and Additional Notes
Species Code	Mandatory	String	Must be a valid ERS species code. Validated against Fish Species master data.
Green Weight Estimate Kg	Mandatory	Number	Decimal to 2dp. Must be 0 or greater

Parameter

Required

Data Type

Validation and Additional Notes

Species Code

Mandatory

String

Must be a valid ERS species code.

Validated against Fish Species master data.

Green Weight Estimate Kg

Mandatory

Number

Decimal to 2dp.

Must be 0 or greater

Lining Create Request Body Example:

{
  "eventHeader": {
    "eventId": "LiningEvent1",
    "tripId": "tr1",
    "completedDateTime": "2017-04-01T08:00:00+13:00",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Some notes",
    "softwareVendor": "ERS-FishServe",
    "softwareVersion": "1.1.2",
    "softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
    "clientNumber": "1234567",
    "completerUserId": "1234"
  },
  "fishingunderhsp": false, 
  "fishingMethodCode": "BLL",
  "targetSpeciesCode": "SNA",
  "mitigationDeviceCodes": ["BIB", "STR"],
  "isIntegratedWeightLineUsed":false,
  "externalWeightKg":41,
  "numberOfHooksPerExternalWeight" : 7,
  "startLocation": {
    "systemDateTime": "2017-04-01T08:00:00+13:00",
    "systemLocation": {
      "longitude": -175.1025,
      "latitude": -45.9878
    }
  },
  "finishLocation": {
    "systemDateTime": "2017-04-01T08:00:00+13:00",
    "systemLocation": {
      "longitude": -175.1025,
      "latitude": -45.9878
    }
  },
  "endOfSetLocation": {
    "systemDateTime": "2017-04-01T08:00:00+13:00",
    "systemLocation": {
      "longitude": -175.1025,
      "latitude": -45.9878
    }
  },
  "startOfHaulLocation": {
      "systemDateTime": "2017-04-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.1025,
        "latitude": -45.9878
      }
   },  
  "isNonFishOrProtectedSpeciesCatchPresent": false,

    "catches": [
      {
        "speciesCode": "SNA",
        "greenWeightEstimateKg": 50.25
      },
      {
        "speciesCode": "CRA",
        "greenWeightEstimateKg": 23.75
      },
      {
        "speciesCode": "HOK",
        "greenWeightEstimateKg": 23.75
      }
  ],

  "hookSpaceMetres": 99,
  "numberOfHooks": 5,
  "bottomDepthMetres": 346,
  "estimatedGreenWeightForAllOtherSpeciesKg": 2,  
  "autolining": true,
  "numberOfLinesHauled": 8
}

Response

Response Status:

Status	Description
201 Created	Status when event has been accepted successfully.
400 Bad Request	Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised	Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

Parameter	Data Type	Validation and Additional Notes
Errors	Array	List of errors, if any. See Errors Parameters below.

Errors Parameters:

Parameter	Data Type	Validation and Additional Notes
Property Name	String	The name of the property that has an error.
Attempted Value	String	The attempted value used.
Error Code	String	The type of error.
Error Message	String	The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v2/lining/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v2/lining/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

Parameter	Required	Data type	Description
Client Number	Mandatory	String	The main permit holder client number that the event is submitted against.
Event ID	Mandatory	String	Unique logbook generated ID for an event.
Software Installation Id	Mandatory	String	Your software installation ID. For example, a13afab2-c409-4622-b8f8-146996587809 Must be the Software Installation Id that was registered with the user and public key.
Completer User Id	Mandatory	String	The user ID retrieved from registering the logbook.

Request Header:

Content-Type: application/json
Signature: signature generated from the digital signature algorithm using the request URL and private key.

Response

Response Status:

Status	Description
200 Ok	Status when event has been retrieved successfully.
404 Not Found	Status when event cannot be found.
401 Unauthorised	Status when the user does not have the appropriate authorisation to perform the action.

Response Body Parameters:

Properties are returned within an Event parameter. Please see the example provided.

Parameter	Data Type
Event ID	String
Trip ID	String
Schema Edition	Number
Event Version	Number
Is Vessel Used	Boolean
Vessel Number	String
Notes	String
Completed By Name	String
Fishing Under HSP	Boolean
Integrated weight line used?	Boolean
External weight (kg)	Number
Number of hooks per external weight	Number
Fishing Method Code	String
Mitigation Device Codes	Array of Strings
Target Species Code	String
Start Location See Geolocation Set Parameters below.	Geolocation Set
Is Non Fish Or Protected Species Catch Present	Boolean
Hook Space Metres	Number
Number of Hooks	Number
Bottom Depth Metres	Number
Is Line Lost	Boolean
End of Set Location See Geolocation Set Parameters below.	Geolocation Set
Start of Haul Location See Geolocation Set Parameters below.	Geolocation Set
Autolining	Boolean
Number of Lines Hauled	Number
Estimated Green Weight for all other Species Kg	Number
Finish Location See Geolocation Set Parameters below.	Geolocation
Completed Date Time	String
Catches See Catches Parameters below.	Array of Catches
Errors	Array
Amendment Reason	String

Geolocation Set Parameters:

Parameter	Data Type
System Location See Geolocation Parameters below	Geolocation
Manual Location See Geolocation Parameters below	Geolocation
System Date Time	String
Manual Date Time	String

Geolocation Parameters:

Parameter	Data Type
Latitude	decimal degrees
Longitude	decimal degrees

Catches Parameters:

Parameter	Data Type
Species Code	String
Green Weight Estimate Kg	Number

Lining Get Request Body Example:

{
  "event": {
    "hookSpaceMetres": 99,
    "numberOfHooks": 5,
    "bottomDepthMetres": 346,
    "isLineLost": null,
    "autolining": false,
    "numberOfLinesHauled": 8,
    "startOfHaulLocation": {
      "systemDateTime": "2017-04-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.1025,
        "latitude": -45.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "endOfSetLocation": {
      "systemDateTime": "2017-04-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.1025,
        "latitude": -45.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "estimatedGreenWeightForAllOtherSpeciesKg": 2,
    "fishingunderhsp": false,
    "isIntegratedWeightLineUsed":false,
    "externalWeightKg":41,
    "numberOfHooksPerExternalWeight" : 7,
    "fishingMethodCode": "BLL",
    "targetSpeciesCode": "SNA",
    "mitigationDeviceCodes": ["BIB", "STR"],
    "startLocation": {
      "systemDateTime": "2017-04-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.1025,
        "latitude": -45.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "finishLocation": {
      "systemDateTime": "2017-04-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.1025,
        "latitude": -45.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "isNonFishOrProtectedSpeciesCatchPresent": false,
    "catches": [
      {
        "speciesCode": "SNA",
        "greenWeightEstimateKg": 50.25,
      },
      {
        "speciesCode": "CRA",
        "greenWeightEstimateKg": 23.75,
      },
      {
        "speciesCode": "HOK",
        "greenWeightEstimateKg": 23.75,
      }
    ],

    "tripId": "tr1",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventId": "LiningEvent1",
    "schemaEdition": 1,
    "eventVersion": 1,
    "clientNumber": "8462926",
    "completedDateTime": "2017-04-01T08:00:00+13:00",
    "notes": "Some notes",
    "amendmentReason": null,
    "completedByName": "Dirk Munroe"
  },
  "errors": []
}

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v2/lining/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v2/lining/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

Parameter	Required	Data type	Description
Client Number	Mandatory	String	The main permit holder client number that the event is submitted against.
Event ID	Mandatory	String	Unique logbook generated ID for an event.

Request Header:

Content-Type: application/json
Signature: signature generated from the digital signature algorithm using the request body and private key.

Request Body Parameters:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

Parameter	Required	Data Type	Description
Event Version	Mandatory	Number	The version of the event that the fisher is wanting to update. Can only update the latest version of an event.

Parameter

Required

Data Type

Description

Event Version

Mandatory

Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Lining Update Request Body Example:

{
  "eventHeader": {
    "eventId": "123qwert",
    "eventVersion": "1",
    "tripId": "tr1",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Lining Update - TEST",
    "amendmentReason": "wrong catch recorded for Hoki",
    "softwareVendor": "ERS-FishServe",
    "softwareVersion": "1.1.2",
    "softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
    "clientNumber": "1234567",
    "completerUserId": "1234"
  },  
  "fishingunderhsp": false,
  "isIntegratedWeightLineUsed":false,
  "externalWeightKg":41,
  "numberOfHooksPerExternalWeight" : 7,
  "fishingMethodCode": "BLL",
  "targetSpeciesCode": "SNA",
  "mitigationDeviceCodes":["ACC"],
  "startLocation": {
    "systemDateTime": "2017-04-01T08:00:00+13:00",
    "systemLocation": {
      "longitude": -175.1025,
      "latitude": -45.9878
    }
  },
  "finishLocation": {
    "systemDateTime": "2017-04-01T08:00:00+13:00",
    "systemLocation": {
      "longitude": -175.1025,
      "latitude": -45.9878
    }
  },
  "endOfSetLocation": {
    "systemDateTime": "2017-04-01T08:00:00+13:00",
    "systemLocation": {
      "longitude": -175.1025,
      "latitude": -45.9878
    }
  },
  "startOfHaulLocation": {
      "systemDateTime": "2017-04-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.1025,
        "latitude": -45.9878
      }
   },  
  "isNonFishOrProtectedSpeciesCatchPresent": false,

    "catches": [
      {
        "speciesCode": "SNA",
        "greenWeightEstimateKg": 50.25
      },
      {
        "speciesCode": "CRA",
        "greenWeightEstimateKg": 23.75
      },
      {
        "speciesCode": "HOK",
        "greenWeightEstimateKg": 24.25
      }
  ],

  "hookSpaceMetres": 2,
  "numberOfHooks": 2,
  "bottomDepthMetres": 2,
  "isLineLost": false,
  "estimatedGreenWeightForAllOtherSpeciesKg": 2,
  "autolining": false,
  "numberOfLinesHauled": 2
}

Response

Response Status:

Status	Description
200 Ok	Status when event has been updated successfully.
400 Bad Request	Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised	Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

Parameter	Data Type	Description
Errors	Array	List of errors, if any. See Errors Parameters below.

Errors Parameters:

Parameter	Data Type	Description
Property Name	String	The name of the property that has an error.
Attempted Value	String	The attempted value used.
Error Code	String	The type of error.
Error Message	String	The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}