The document type definition (DTD) file provides a contract between the Designer API portion of Designer and Workflow Manager. It is the job of the WMS integration to break down the design tables, which will be stored differently for different systems, into the XML format provided in the DTD. The DTD is a kind of schema for every method that takes a form of XML. If the XML does not match the DTD, a parsing error will be generated.

Work Request Top Level Element

The work request top level as defined in the Design schema has a few extra elements on it to enable the application programmer to modify the default behavior of Designer when it loads a design. The work request top level is defined like this in the design XML schema:

<!ELEMENT WORKREQUESTTOPLEVEL (DATABASE?, TITLEBAR?, VIEWONLY?, STOREDDISPLAY?,
STOREDTEMPLATE?, COPYFROMSD?, DESIGNER_VERSION?, DEFAULT_PARENT_VERSION?,
(WORKREQUEST*))>

• The DATABASE element on WORKREQUESTTOPLEVEL allows the application programmer to pass the database back to Designer from the XML.

• The TITLEBAR element on WORKREQUESTTOPLEVEL allows the application programmer to set the ArcMap caption when the work request is loaded. Otherwise, the caption is set from the description of the work request and design elements.

• The VIEWONLY element does not contain any text. If it is present on WORKREQUESTTOPLEVEL, then the design will be opened as read-only, and no edits will be allowed.

• STOREDDISPLAY sets the current stored display for the work request. Although optional on the top level, setting the stored display correctly is critical because it supplies the graphics, the display settings, and the workspace for the compatible units. The default behavior of MMDesignerImpl is to create and save a stored display from the version names of the work request and design. If the version elements are not present, then it will look for the stored display element on the top level. The stored display element has an owner attribute that specifies whether it is system or user level. The owner attribute defaults to system if it is not specified.

• STOREDTEMPLATE allows the application programmer to specify a template to load with their work request. A page template defines the size, orientation, and map elements for a standard map. See the Using ArcFM Solution online help in ArcMap for information about map production.

• COPYFROMSD supports the Copy Design tool. This is the stored display of the original design.

• DESIGNER_VERSION contains the current build number (visible on the About ArcFM Solution screen) for users who are NOT using Workflow Manager.

• DEFAULT_PARENT_VERSION specifies the parent version of the design.

• WORKREQUEST means a WORKREQUESTTOPLEVEL must have one or more work requests under it.

Work Request, Design, Work Location, and CU Elements

The element definitions for work requests, designs, work locations, and CUs are very similar, so they are considered together here. A WORKREQUEST may contain design(s). A DESIGN may have multiple work locations and/or CUs under it. And a WORKLOCATION may have one or more CUs under it. In the samples below, the pipe (|) deliminated values indicate the elements that may be contained within that element.

   <!ELEMENT WORKREQUEST (DESIGNER_ID?, DESCRIPTION?, ID?, VERSION?, 
        WF_STATUS?, METADATA?, DEFNODE?, EDM?, SPATIAL_WORKREQUEST?, OID?, 
        (DESIGN? | WORKREQUEST?))>

        <!ELEMENT DESIGN (DESIGNER_ID?, DESCRIPTION?, ID?, COPYFROMID?, VERSION?, 
        WF_STATUS?, METADATA?, DEFNODE?, DESIGN_NUMBER?, EDM?, OID?, 
        (WORKLOCATION | GISUNIT | CU | CUDEF_ATTRIBUTE)*)>

        <!ELEMENT WORKLOCATION (DESIGNER_ID?, DESCRIPTION?, ID?, WF_STATUS?, 
        METADATA?, DEFNODE?, EDM?, OID?, (GISUNIT | CU | CUDEF_ATTRIBUTE)*)>

        <!ELEMENT CU (WMS_CODE?, DESIGNER_ID?, DESCRIPTION?, UNIT_OF_MEASURE?, 
        LENGTH?, WORK_FUNCTION?, WF_STATUS?, METADATA?, CUNAME*, TABLENAME?, 
        SUBTYPE?, QUANTITY?, EDM?, CUDEF_ATTRIBUTE*)>
        

• The DESIGNER_ID element is the OID of the feature corresponding to the work request, design, or work location. The DesignerID field on the CU does not represent the OID of the feature for the CU. This allows Designer to find the corresponding feature for the design objects. The other two components that link these to the features are the workspace and the table name. The workspace is determined by the stored display and the table name is determined by the model name on these feature classes. If the DESIGNER_ID is not present, then there will be no shape for that object in the Attribute Editor. Note that the WMS must store the DESIGNER_ID provided by the DesignerAPI in order to find the associated GeoObject, or feature.

• The DESCRIPTION element provides the value for the description property on the corresponding design object. This value is displayed in the Attribute Editor.

• The ID element corresponds to the Work Request ID, the Design ID, and the Work Location ID for work requests, designs, and work locations respectively.

• COPYFROMID is the design ID of the original design (when using the Copy Design tool).

• The VERSION element contains the version name information. This is stored separately for work requests and designs. This way the user may have separate versions for each design, or group them under a single version at the work request level. It is defined with these children:

<!ELEMENT VERSION (NAME, DESCRIPTION?, ACCESS?, BASE?)>

• The NAME element contains the name of the version. In a typical implementation, this is probably the name of the work request or design. The NAME element must always be present as a child of VERSION. MMDesignerAPI initially creates the version with the name specified here and then uses it to find it later when switching to existing versions.

• DESCRIPTION is an optional element that is written to the version description when it is created.

• ACCESS describes whether the version is private, protected, or public. Any user logged into an SDE server can view and edit a public version. Only one user can view or edit a private version. A protected version means everyone may view it, but only a supervisor can post changes back to it.

• BASE designates the parent version. When BASE is specified, the new version is created from and will eventually be posted back to that base version. Otherwise, the version is created from and posted back to the SDE default version.

• WF_STATUS contains the work flow status (e.g., In Design, Pending Approval, etc.). The numeric value will correspond with a value in the Work Flow Status domain.

• The METADATA element is a special element to store information important to the WMS but not critical to the operation of Designer. Labor type and soil type are two examples of metadata. The Attribute Editor hosts custom metadata OCX’s for each feature class. The developer writes their custom control, implements the IMMCustomFieldEditor interface and registers it in the M&M Metadata Editor component category. Then the metadata editor is configured in the ArcFM Properties Manager on the Field Info tab. When a design object is selected, the proper metadata editor is loaded. This OCX is responsible for concatenating the metadata into a string and then setting the metadata property on the work request, design, work location, or CU. The metadata property can be accessed by a QI to the IMMDesignAttributes interface on the list item.

• DEFNODE is a simple element, without text, that determines which of the design objects will be designated as the default or active node. The DEFNODE element should only appear once in the work request structure. If it appears more than once, the first element with DEFNODE is marked as the default. If it doesn’t appear at all, the first design is marked as the default.

• DESIGNNUMBER is for internal use only.

• The EDM element is designated to store information important to the WMS but not critical to the operation of Designer. This element supports Extended Data Manager (EDM). In Designer 8.3, EDM replaced Metadata with more flexible functionality for maintaining this WMS data. Metadata is still supported. The EDM element contains EDM property (EDMPROP) elements. An EDM property element contains a name attribute that corresponds with a field in an Extended Data Definition (EDD) table. The extended data property can be accessed by a QI to the IMMDesignAttributes2 interface on the list item.

• SPATIAL_WORKREQUEST is used to specify the feature in the GIS at which to locate the work request.

• OID is for internal use only.

• CUDEF_ATTRIBUTE is for internal use only.

• WMS_CODE is the code that the WMS uses to reference a particular CU. For example, “PW45-H2” means a 45-foot wood pole, or “XFMO 14KV 240/480V” means a 14KV transformer. Designer uses WMS_CODE to cross-reference a particular CU in a design to their definition in the CU library. If the WMS_CODE is not present, the design CU will not be able to find its associated feature.

• DESIGNERID under CU does not represent the OID of the feature for the CU. DesignerID is the primary key in the Designer Feature tables. See the description above for more details.

• UNIT_OF_MEASURE is the type of length unit used to measure a linear feature. Point features, such as transformers or fuses, will have a UNIT_OF_MEASURE of ‘each.’ Linear features, such as primary conductor, may have either English units (feet, inches, etc.) or metric units. Note that these values are passed in the XML as integer codes which may need to be translated for cost estimates.

          mmd8uomEach             =       0
          mmd8uomMiles            =       50
          mmd8uomFeet             =       51
          mmd8uomInches           =       52
          mmd8uomKilometers       =       100
          mmd8uomMeters           =       101
          mmd8uomCentimeters      =       102
  

• QUANTITY specifies the number of a CU. (A non-GIS CU is one that is stored in the WMS and the design, but does not have a corresponding feature in the geodatabase). For example, the user might define four identical pole accessories in a design as one CU with a quantity of four, rather than as four separate CUs. In contrast, a 45-foot pole will always have a quantity of one. Multiple poles with the same definition will be separate CUs, each with their own associated feature. If the CU corresponds to a row in the geodatabase, then the Quantity value is always 1. If the CU does not correspond to a row in the geodatabase (non-GIS CU), then the value may exceed 1.

• LENGTH also applies only to linear features. The MMDesignerAPI first looks for a field with the model name “MEASUREDLENGTH.” If that is not present, it will use the length field of the feature, which is maintained by ArcMap. The logic behind this is that the length of the feature in map units may not be accurate enough for some applications, so a manually entered value for length will take precedence over an automatically maintained value.

• WORK_FUNCTION is the current work function of the CU in the design. Work functions indicate which project phase the CUs are in (e.g. a work function of Install indicates that the CU will be added as part of the current design). Work function values are also passed as integer codes. The code provided for WORK_FUNCTION should have a matching code/description in the ‘Work Function’ domain present in your Designer geodatabase. This domain is created by the Create ArcFM Solution Tables tool in ArcCatalog. The sample implementation uses the following codes:

          None            =       0
          Install         =       1
          Remove          =       2
          Replace         =       4
          Transfer        =       8
          Retire          =       16
          Abandon         =       32
  

It is important to note that the Work Function domain can be set up differently than the sample implementation. Setting up the codes and descriptions contained by the Work Function domain is left to the implementer’s discretion.

Send Comment to ArcFMdocumentation@schneider-electric.com