FSP TRACKING SYSTEM. FSP ESF Submission Guide. Ministry of Forests and Range Information Management Group Date: June 15 th, 2008

Size: px

Start display at page:

Download "FSP TRACKING SYSTEM. FSP ESF Submission Guide. Ministry of Forests and Range Information Management Group Date: June 15 th, 2008"

Kelley Lawson
5 years ago
Views:

FSP TRACKING SYSTEM FSP ESF Submission Guide Client: Ministry of Forests and Range Information Management Group Date: June 15 th, 2008 Revision: 7

1 FSP TRACKING SYSTEM FSP ESF Submission Guide Client: Ministry of Forests and Range Information Management Group Date: June 15 th, 2008 Revision: 7 (Rls1.3) Vivid Solutions Inc. Suite #1A, 2328 Government St. Victoria, BC V8T 5G5 Phone: (250) Fax: (250) Website:

2 Document Change Control REVISION NUMBER DATE OF ISSUE AUTHOR(S) DESCRIPTION 1 June 8 Vivid Solutions Original draft 2 September 12, 2006 Vivid Solutions Reviewed by R. Yee 3 March 19, 2008 CGI Update for FSP April 15, 2008 CGI Update Document Structure image 5 May 23, 2008 Vivid Solutions Update element diagrams 6 June 15 th, 2008 CGI Update for FSP July 24, 2008 Vivid Solutions Update element diagrams and field lengths Page 2 of 24

3 Table of Contents 1. OVERVIEW WHAT IS A SUBMISSION? XML? GML? WHO CAN MAKE A SUBMISSION? HOW DO I MAKE A SUBMISSION? DOCUMENT STRUCTURE COMPONENT DETAILS ESF SUBMISSION SUBMISSION METADATA SUBMISSION CONTENT FSP SUBMISSION FSP SUBMISSION METADATA SUBMISSION ITEM FOREST STEWARDSHIP PLAN FDULIST FDU IDENTIFIEDAREALIST IDENTIFIEDAREA STANDARDS DATA TYPES ANYURI BOOLEAN CODE TYPES DATE TELEPHONE NUMBERS GEOMETRY GML Page 3 of 24

4 1. OVERVIEW This document is a guide for creating submissions for the FSP Tracking System (FSPTS) application. It is intended to assist submission authors in producing valid Forest Stewardship Plan submission documents, and as a guide for developers that will be creating automated tools for this purpose. The components of a valid FSP submission are described in the order they should appear in a submission document and an example is provided. A Business Rules section is also included that discusses the business rules, regulations and restrictions in regards to the data being submitted. 1.1 WHAT IS A SUBMISSION? A submission is an XML document that is uploaded via the ESF website for processing by application specific systems, in this case FSPTS. It allows both attribute and spatial data to be submitted in a single file. Spatial data will be embedded using GML. An FSP submission document can contain: Client information Forest Development Units (FDU), including spatial map Stocking standards Amendment information The original FSP submission must also have a legal FSP document as an attachment. This will typically be the formal FSP Plan, as a Microsoft Word (.doc) or Portable Document Format (.pdf) file. Any submission may include other supplementary documents (such as PDF maps) as attachments. 1.2 XML? GML? Extensible Markup Language (XML) is a language for documents that contain structured data. It uses a format that is easily readable by both humans and computers and is a standard supported by the W3C, the standards body for the World Wide Web. It has emerged as the primary format for encoding structured information. Many tools are available for authoring, translating and viewing XML documents. Geography Markup Language (GML) is a subset of XML that allows for the encoding of geographic information; including both the spatial and non-spatial properties of geographic features. 1.3 WHO CAN MAKE A SUBMISSION? Clients of the Ministry of Forests and Range (MoFR) can make FSP-type ESF submissions. A role of FSP Submitter is required to submit via ESF. Page 4 of 24

5 Though it is not strictly necessary, users who are familiar with XML, GML, or even HTML should find the creation of these documents very straightforward. If you are unfamiliar with any of these acronyms, the ESF website ( has some resources that may be helpful. 1.4 HOW DO I MAKE A SUBMISSION? 1. Create the document, following the instructions in this guide (samples are provided in this document and are available for download on the website) 2. Save it as an.xml file (a text file with an extension of.xml) Client Create the submission document 3. Logon and upload the document via the ESF submission website 4. When requested, select and send any required attachments. (The initial FSP submission requires you to attach the legal FSP document. Other documents, such as supplementary maps, may also be attached. The number of documents you plan to attach is specified in the xml submission file in the <attachmentcount> element) Failure Message Client Upload to ESF submission website ESF Validate the document structure Error notification The document structure and geometry data will be validated immediately upon upload. You ll be notified if there s a problem so that you can fix it and try again. Once it has passed the initial validation, the submission is sent to the FSP Tracking business system that will apply further checks on the actual content. If those fail, the submitter will receive a message through the website requesting it be fixed. Business Appl Validate the document content Business App Appropriate processing Note that acceptance of your submission by MoFR does not imply a decision (approve/reject) on the Forest Stewardship Plan. The submitter will be notified by when the MoFR District Office has made a decision on the plan. Page 5 of 24

6 2. DOCUMENT STRUCTURE The formal and detailed specification for the FSP XML Schema can be found at: The schema is documented on line at a readily-available MoFR site to ensure the Forest industry has timely access. The diagram below describes the overall structure of an FSP submission document. Not all components are mandatory and some can be represented more than once, e.g. multiple FDUs can be contained within a single document. Detailed discussions of each component can be found in the Component Details section, following the diagram. Page 6 of 24

7 ESF Submission * Structural Tags Submission Metadata * Submission specific content Submission Content * Multiple allowed per parent section Spatial data inclduded i FSP Submission * Mandatory * FDUList FSP Submission Metadata * Submission Item * Forest Stewardship Plan * FDUList i Stocking Standards Identified Area List i Page 7 of 24

2.1 COMPONENT DETAILS Note: In the descriptions below, schema elements documented in red represent additions or changes to the FSP schema between version 1 and the current version (version 2). 2.1.1 ESF SUBMISSION Required.

8 2.1 COMPONENT DETAILS Note: In the descriptions below, schema elements documented in red represent additions or changes to the FSP schema between version 1 and the current version (version 2) ESF SUBMISSION Required. Each submission document starts with information required to carry out correct XML processing. This information will be identical for each submission document, with the exception of the version number. The Submission Header defines several things: The element esf:esfsubmission indicates that this is a submission to be processed via the ESF. The namespaces (xmlns) used in FSP submission documents are defined The schemalocation attribute associates the namespaces with a URL that indicates the version of the schema being used. Tip: The version specified in the header must match the version of the schema you are using, i.e. the schema you downloaded from the website SUBMISSION METADATA Required. The ESF submission metadata includes contact information for the submitting party. This is required to process the submission SUBMISSION CONTENT Required. This is the container for the submission details. It includes required structure tags as well as some optional descriptive information. Page 8 of 24

2.1.4 FSP SUBMISSION Required. This element informs the system that a Forest Stewardship Plan (FSP) is being submitted. 2.1.5 FSP SUBMISSION METADATA Required.

9 2.1.4 FSP SUBMISSION Required. This element informs the system that a Forest Stewardship Plan (FSP) is being submitted FSP SUBMISSION METADATA Required. This contains information about a contact person for the FSP itself (which might be different from the ESF contact). While flagged in Version 1.0 of the schema as optional, these elements are actually mandatory: <licenseecontact>, <telephonenumber>, < address> for both original submissions and amendments. Page 9 of 24

licenseecontact: Required. The name of a person who can be contacted by the MoFR District office to speak to the FSP submission. telephonenumber: Required.

10 licenseecontact: Required. The name of a person who can be contacted by the MoFR District office to speak to the FSP submission. telephonenumber: Required. A telephone number for the licensee contact person. address: Required. An address for the licensee contact person. attachmentcount: Required. The number of attached documents to be included with this FSP submission. Attached documents are ideally submitted during the same ESF session; however, they may be submitted at any time within 72 hours of the core XML submission. The original FSP application must include a legal FSP document as an attachment; so for the original submission, this number should be (at least) SUBMISSION ITEM Required. This is a structural tag to contain the actual submission data. Page 10 of 24

11 2.1.7 FOREST STEWARDSHIP PLAN Required. This element contains the actual submission data for the FSP. It contains an indicator to say whether the submission is an original FSP, or an amendment to an existing FSP. In the case of an amendment, it also provides an indicator to the MoFR as to whether the amendment requires Ministry approval or not. Some FSP administrative overhead information is also provided here: fspid: this will be a unique number assigned by the MoFR on initial submission. The number will identify the FSP during subsequent amendment submissions. (Conditional: must be provided for any but the original submission). amendmentid: this will be the amendment number the submission refers to, on update. The number will identify the FSP s amendment number, during subsequent amendment submissions. (Conditional: must be provided for update submissions). planname: Required: the submitter will provide a name for the FSP on the original submission and any amendment. licenseeamendmentname: Optional: this will be the user defined amendment name. This field is provided to allow the submitter to identify amendments. actioncode: Required: this one-letter code allows the System to accept updates and amendments) to an FSP submission. Set it to I (Input) for the initial submission. For an amendment, set the code to A. If the District Manager requests further information by putting the FSP in Draft status, set the actioncode to U to do the updates (this applies for updates to either an original submission or an amendment). Note: MoFR District staff or service providers should set a value of U for special submission of spatial information (FDUs) only. planholderlist: Required: a list of the Forest Licence numbers of all Agreement holders participating in the plan. The way to remove an agreement holder from the FSP is to submit an amendment with that licence number removed from planholderlist. plantermyears: Optional: Submitter may provide a number from 1 to 5 to represent the suggested term of the submitted plan in years. plantermmonths: Optional: Submitter may provide a number from 1 to 11, to represent the suggested term of the submitted plan in months. plantermexpiry: The date where the FSP term expires. districtcodelist: Required: this list is a container for one or more MoFR Forest Districts which are affected by the FSP. Page 11 of 24

12 amendmentind: Required: If the submission is an amendment, set this value to true (or 1 ). If this is the original submission (or an update), set the value to false (or 0 ). Amendment Comment: Optional: This text field provides a place to describe what is being amended for an amendment submission. While optional, the user is strongly encouraged to provide information so that decision makers know what you are changing in your FSP. AmendmentApprovalRequiredInd: Required: This mandatory flag indicates to the MoFR whether the FSP submission requires ministry approval. It should be set to true for the original submission (amendment 0). For amendments to existing FSPs, set the flag true if the amendment will require ministry approval; otherwise, set it to false legaldocconsolidatedind: Optional: This flag indicates that the FSP Legal Document to be attached through ESF is a consolidated version of the entire FSP. District will automatically set as true for Original FSP submissions. fduupdateind: Optional: This flag indicates that the FDU of the FSP will be updated in this amendment. identifiedareasupdateind: Optional: This flag indicates that the Identified Areas of the FSP will be updated in this amendment. stockingstandardupdateind: Optional: This flag indicates that there will be stocking standard records added in this amendment. frpa197ind: Optional: Indicates whether the licensee has made an election under FRPA 197 legislation to roll over cut blocks under the Forest Stewardship Plan. transitionalind: Optional: Indicates that the Original FSP being submitted is a Transitional FSP. FDUList: described below (Conditional: should be present in original submission; however, the FSP can be submitted without the FDUs. Note that the FSP cannot be approved until the FDUs are in place) Stocking Standards: described below (Conditional: must be submitted at some point before the FSP can be approved.) identifiedarealist: described below (Conditional: should be present in original submission; however, the FSP can be submitted without the IAs.) Page 12 of 24

13 Page 13 of 24

14 Page 14 of 24

15 2.1.8 FDULIST Conditional: The FDUList element is a container to hold one or more Forest Development Units that are included with each original FSP. If this element is included, it must contain at least one FDU element FDU Conditional: An FDU (for Forest Development Unit) is composed of: A name A list of forest licences that apply to the area in the FDU An electronic map of the boundaries of the FDU See the section below on GML and electronic maps. The original FSP submission must contain at least one FDU before it can be approved (although the FDUs may be submitted separately from the base submission). Later amendment submissions may or may not contain FDU elements. The following elements make up an FDU. All of an FDU s elements are mandatory, if the FDU is submitted: gmlboundedby: This is a mandatory section which helps the System recognize that spatial information is following. A typical value for this element is: <gml:boundedby> <gml:null>inapplicable</gml:null> </gml:boundedby> fduname: Each FDU must have a name supplied by the licensee. It can be any value, and should not match the name of any other FDU in the FSP. licencelist: This is a simple list of all Forest Licence Numbers that apply within the boundary of this FSP. (In multiple-agreement holder FSPs, more than one licensee may have obligations within a single FDU.) extentof: This element contains the GML-encoded spatial data describing the geographical boundaries of this FDU. See the section below on GML and spatial data. If an amendment contains changes to any of the FDU data, all the FDUs in the FSP must be re-submitted. (That is, in a multi-fdu FSP, you cannot submit changes to just one FDU: all the FDUs must be submitted again, including spatial (GML) data. FDUs that are left out of an amendment (compared to the original submission) will be deleted by the System. Page 15 of 24

2.1.10 IDENTIFIEDAREALIST Conditional: The identifiedarealist element is a container to hold one or more Identified Areas that are included with each original FSP.

16 IDENTIFIEDAREALIST Conditional: The identifiedarealist element is a container to hold one or more Identified Areas that are included with each original FSP. If this element is included, it must contain at least one identifiedarea element IDENTIFIEDAREA Conditional: An identified area is composed of: A name The legislation type of the Identified Area being included. An electronic map of the boundaries of the Identified Area The following elements make up an identified area. All of an identified area s elements are mandatory, if the identified area is submitted: gmlboundedby: This is a mandatory section which helps the System recognize that spatial information is following. A typical value for this element is: <gml:boundedby> <gml:null>inapplicable</gml:null> </gml:boundedby> Page 16 of 24

identifiedareaname: Each Identified Area must have a name supplied by the licensee. It can be any value, and should not match the name of any other Identified Area in the FSP.

17 identifiedareaname: Each Identified Area must have a name supplied by the licensee. It can be any value, and should not match the name of any other Identified Area in the FSP. legislationtypecode: Each Identified Area must have a legislation type supplied by the licensee. It can be any valid legislation type value. extentof: This element contains the GML-encoded spatial data describing the geographical boundaries of this Identified Area. See the section below on GML and spatial data. If an amendment contains changes to any of the Identified Area data, all the Identified Area in the FSP must be re-submitted. (That is, in a multi-identified Area FSP, you cannot submit changes to just one Identified Area: all the Identified Areas must be submitted again, including spatial (GML) data. Identified Areas that are left out of an amendment (compared to the original submission) will be deleted by the System. Page 17 of 24

18 STANDARDS Conditional: One or more Stocking Standards (also known as Standards Regimes) must be submitted with the original FSP. These are like the Stocking Standards familiar to users of RESULTS, with only a few minor differences. Under certain circumstances, licensees may use existing pre-approved stocking standards, which are default standards. The schema allows submission of: district default stocking standards (by Stocking Standard ID) new, fully-described stocking standards a combination of both In the following diagram, default standards would be included as a list of StockingStandardID values; whereas new, fully-described stocking standards would be listed under the newfspstandardslist container element Page 18 of 24

19 For the fully-described Stocking Standards, here is the layout: standardsregimename: A text name for the stocking standard, up to 50 characters. standardsobjective: A text description of the overall objective for this stocking standard. regenobjectives: States details of regeneration and free growing milestones proposed for this standard. geographicdescription: A general, text-based description of the geographical area within which this standard may be applied. additionalstandards: Optional comments to elaborate on the standard, or state additional conditions or circumstances that apply. BGCList: A list of the BioGeoClimatic zones that are compatible with this stocking standard. standardslayerlist: A list of forest layers considered in this stocking standard; different silviculture practices and species may apply in different layers. A full description of the various fields and possible values for stocking standards can be found at: Page 19 of 24

20 Page 20 of 24

21 3. DATA TYPES There are several data types that have specific requirements. This section describes the proper syntax and formatting to be used when entering content for these types. 3.1 ANYURI This is a standard XML data type for representing a Uniform Resource Identifier. For the purposes of FSP they are used for addresses; the mailto: prefix should be used as in the example. Example: <fst: address>mailto:john.doe@majorlicensee.com</fsp: address> 3.2 BOOLEAN In XML, Boolean (logical) values can be given as either 1/0 or true/false. The name of a Boolean field always indicates the effect of a true value. Thus AmendmentInd indicates that if the field has a value of true, the submission should be processed as an amendment. Example: <fsp:amendmentind>1</fsp:amendmentind> 3.3 CODE TYPES The only pre-defined codes defined for FSP Submissions are those involving Stocking Standards. For pre-defined codes for the Stocking Standards section of the submission, see the Code Table section at: DATE In XML, dates must always be given in the format YYYY-MM-DD. Thus indicates April 10, Example: <fsp:submissiondate> </fsp:submissiondate> Page 21 of 24

22 3.5 TELEPHONE NUMBERS Telephone numbers use the custom data type, TelephoneNumberType. A valid telephone number must be 10 digits, starting with the area code. Example: <fsp:telephonenumber> </fsp:telephonenumber> 3.6 GEOMETRY Geometry content is made up of two components: spatial metadata and the feature itself. Metadata is information about the data itself, for example how it was captured. The tags for both components are mandatory but the content is optional. ESF will validate several types of geometry. For RESULTS, the acceptable types are: Point Linestring Polygon MultiPolygon Polygon with multiple holes Page 22 of 24

23 3.6.1 GML Geometry is represented as GML; the fsp:extentof tags are used to delineate the GML tags. The following exemplify the syntax for all geometry types that are acceptable in an FSP submission document. Spatial Coordinate Systems: ESF requires spatial objects in submissions to specify the coordinate system used to represent them. The srsname attribute is used to define this. Note that it is permissible (but not recommended) that different coordinate systems can be used within the same submission. Refer to the following table in the Code Tables for valid entries. SRS NAME EPSG:4326 EPSG:32607 EPSG:32608 EPSG:32609 EPSG:32610 EPSG:32611 EPSG:42102 EPSG:4269 EPSG:26907 EPSG:26908 EPSG:26909 EPSG:26910 EPSG:26911 COORDINATE SYSTEM WGS 84 (Geographics) WGS 84 / UTM zone 7N WGS 84 / UTM zone 8N WGS 84 / UTM zone 9N WGS 84 / UTM zone 10N WGS 84 / UTM zone 11N NAD83 BC Albers NAD83 (Geographics) NAD83 / UTM zone 7N NAD83 / UTM zone 8N NAD83 / UTM zone 9N NAD83 / UTM zone 10N NAD83 / UTM zone 11N Page 23 of 24

24 GML Examples: <fsp:extentof> <gml:polygon srsname="epsg:42102"> <gml:outerboundaryis> <gml:linearring> <gml:coordinates>2271.0, , , , ,1000.0</gml:coordinates> </gml:linearring> </gml:outerboundaryis> </gml:polygon> </fsp:extentof> <fsp:extentof> <gml:multipolygon srsname="epsg:42102"> <gml:polygonmember> <gml:polygon> <gml:outerboundaryis> <gml:linearring> <gml:coordinates>2237.7, , , , ,2513.4</gml:coordinates> </gml:linearring> </gml:outerboundaryis> <gml:innerboundaryis> <gml:linearring> <gml:coordinates>2737.7, , , , ,2983.1</gml:coordinates> </gml:linearring> </gml:innerboundaryis> </gml:polygon> </gml:polygonmember> <gml:polygonmember> <gml:polygon> <gml:outerboundaryis> <gml:linearring> <gml:coordinates>988.7, , , , ,2524.7</gml:coordinates> </gml:linearring> </gml:outerboundaryis> </gml:polygon> </gml:polygonmember> </gml:multipolygon> </fsp:extentof> <fsp:extentof> <gml:polygon srsname="epsg:42102"> <gml:outerboundaryis> <gml:linearring> <gml:coordinates>1000.0, , , , ,1000.0</gml:coordinates> </gml:linearring> </gml:outerboundaryis> <gml:innerboundaryis> <gml:linearring> <gml:coordinates>1168.0, , , , ,1227.8</gml:coordinates> </gml:linearring> </gml:innerboundaryis> <gml:innerboundaryis> <gml:linearring> <gml:coordinates>1643.6, , , , ,1606.3</gml:coordinates> </gml:linearring> </gml:innerboundaryis> </gml:polygon> </fsp:extentof>

ELECTRONIC SUBMISSION FRAMEWORK (ESF)

ELECTRONIC SUBMISSION FRAMEWORK (ESF) LEXIS (Log Export Information System) SUBMISSION GUIDE FOR PROVINCIAL APPLICATIONS Client: Ministry of Forests Information Management Group Date: April 8, 2008 Revision: