TRAINING GUIDE Overview f Lucity Spatial
Overview f Lucity Spatial In this sessin, we ll cver the key cmpnents f Lucity Spatial. Table f Cntents Lucity Spatial... 2 Requirements... 2 Supprted Mdules... 3 Hw it wrks... 3 Behind-the-scenes... 4 Setup... 5 Assign default map services... 5 Cnfigure Default Gecding Service... 6 Cnfigure System Settings... 6 Frce Spatial Recrd Prcessing... 7 ArcMap... 8 Generating Live Wrk Layers... 8 Publishing Live Wrk Layers... 14 ArcGIS Pr... 16 Mdule Spatial Data Tl... 16 Lucity Web Map... 19 Mdule Spatial Data Tl... 19 Trubleshting... 21 Admin Prtal Tl... 22 Data Quality Tl... 23 Overview f Lucity Spatial (v2018 & 2018r2) 1
Lucity Spatial Since versin 2014 Lucity ffers the ability t stre wrk rder and wrk request spatial cmpnents directly in the Lucity database. String the spatial cmpnent (gemetry) in the Lucity database allws fr faster analysis, better efficiency, and mre flexibility when shwing these lcatins in a map. Requirements A few requirements must be met befre implementing Lucity Spatial: The Lucity database must be ne f the fllwing: SQL Server 2008 r higher Oracle with MDSYS.SDO_GEOMETRY data type enabled The Lucity Services must be installed Each Lucity linked feature class must be assigned t a default map service Lucity linked feature classes must be ne f the fllwing gemetry types: Pint Line (including multi-line features) Plygn (including multi-plygn features) System Settings in UI Admin must be cnfigured: The Enable Lucity Spatial system setting must be set t TRUE The Max amunt f days t prcess spatial histry must be set t a value greater than 0 A default Gecding Service must be defined This is set in the Lucity Administratin GIS Services The gecding service must be n versin 10.2 r higher (supprting single line input) Ntes: Overview f Lucity Spatial (v2018 & 2018r2) 2
Supprted Mdules Lucity Spatial is enabled with the fllwing mdules: Wrk: Requests, Wrk Orders, PM/Templates, Master Prject Management, Sub Prject Management, Wrk Permits Sewer: PACP Inspectins, TV Inspectins, Smke Testing, Building Inspectins, Sewer Overflws Strm: PACP Inspectins, TV Inspectins Water: Water Flushing Rutes, Mainbreaks (distributin, recycled, raw) Street: Street Rutes, Sidewalk Inspectins Hw it wrks As recrds are created, updated, and deleted in Lucity, a Lucity service prcesses the changes and adds the spatial lcatin (gemetry) directly int the Lucity database. This spatial infrmatin can then be easily retrieved and viewed with the Lucity tls prvided in ArcMap, ArcGIS Pr, and the Lucity web map. Overview f Lucity Spatial (v2018 & 2018r2) 3
Behind-the-scenes The fllwing Lucity tables and views are used with Lucity Spatial: WKSPATIALCHANGE This table is updated autmatically by the Lucity applicatin with any change made t Wrk Requests and Wrk Orders that deal with lcatin infrmatin. The Lucity Spatial Updater service prcesses these recrds by btaining their crrespnding gemetries WKGEOMPT- This table stres all pint gemetries ppulated by the Lucity Spatial Updater service retrieved when prcessing WKSPATIALCHANGE WKGEOMLN- This table stres all linear gemetries ppulated by the Lucity Spatial Updater service retrieved when prcessing WKSPATIALCHANGE WKGEOMPG- This table stres all plygn gemetries ppulated by the Lucity Spatial Updater service retrieved when prcessing WKSPATIALCHANGE GIS_WKGEOMLNRQ- View shwing all linear Request lcatins GIS_WKGEOMPGRQ- View shwing all plygn Request lcatins GIS_WKGEOMPTRQ- View shwing pint Request lcatins (asset nly) GIS_WKGEOMPTRQLOC- View shwing pint Request lcatins (address and x/y) GIS_WKGEOMLNWO- View shwing all linear Wrk Order lcatins GIS_WKGEOMPGWO- View shwing all plygn Wrk Order lcatins GIS_WKGEOMPTWO- View shwing pint Wrk Order lcatins (asset nly) GIS_WKGEOMPTWOLOC- View shwing pint Wrk Order lcatins (address and x/y) Ntes: Overview f Lucity Spatial (v2018 & 2018r2) 4
Setup Assign default map services The Lucity Spatial Updater service interacts with map services t btain an asset s gemetry t stre in the Lucity database. T btain the gemetry fr an asset the fllwing prcess is fllwed: 1. Determine the list f feature classes linked t a given asset type 2. D the fllwing fr each feature class until the asset gemetry is returned: a. Determine the map service i. If a map service is defined at the feature class level, then that ne will be used. ii. If a map service isn t defined at the feature class level, then the ne defined at the gedatabase level will be used. b. Query the map service fr the asset i. If it exists, return the gemetry ii. If it desn t exist, mve t the next feature class The gedatabase map service is defined in the Gedatabase Cnfiguratin Tl in ArcCatalg. It is listed under the Cnnectin Prperties tab when yu have a gedatabase nde selected. A service defined at the feature class level will be listed under the Edit Map Service tab when yu have the feature class nde selected. Overview f Lucity Spatial (v2018 & 2018r2) 5
Cnfigure Default Gecding Service In UI Admin s GIS Services, the fllwing must be cnfigured: 1. On the Utility Services tab, cnfigure a gecding service with Lucity and make sure t set a default as shwn in the red utline belw: Cnfigure System Settings In UI Admin, system settings the fllwing must be cnfigured: 1. On the GIS tab, set the Enable Lucity Spatial t TRUE 2. On the General tab, adjust the Max amunt f days t prcess spatial histry (must be greater than 0). a. Example: If yu enter 180, the Lucity Spatial Updater will prcess all wrk rders/requests mdified tday and within the last 180 days. b. Nte: The Lucity Spatial Updater service is reliant n back end cnfiguratin that was added t the Lucity database in 7.4. Therefre, depending n yur upgrade histry there culd be a few years wrth f lcatins that have the ptential t be prcessed. Overview f Lucity Spatial (v2018 & 2018r2) 6
Frce Spatial Recrd Prcessing Once yu have cmpleted the cnfiguratin and setup f Lucity Spatial, yu may find the need t frce spatial recrd prcessing f existing wrk and inspectin data. Please refer t the Hw it Wrks sectin fr further details n hw Lucity Spatial perates, but in simple terms it will nly prcess Lucity wrk and inspectin recrds that are inserted r updated nce Lucity Spatial has been enabled fr a particular mdule. Fr example, yu have just upgraded t 18r2 and wuld like t see the mst recent sewer smke test bservatins in the map. Since sewer smke test bservatins were nt supprted with Lucity Spatial until versin 18r2, smke bservatin recrds added prir t 18r2 wuld nt have been prcessed. Therefre, t see thse smke bservatins in the map, yu first need t run the Frce Spatial Recrd Prcessing tlkit against thse recrds. 1. Open the Lucity Mdule View fr the wrk r inspectin mdule. 2. Yu can either filter yur recrds t be nly thse that yu are interested in prcessing r run it n a selectin. a. If yu have a large amunt f data, it is recmmended that yu use a filter and limit it t nly include the necessary recrds. 3. On the mdule tlbar, click the Tlbx buttn, and yu shuld see a cuple f ptins pertaining t Frce Spatial Recrd Prcessing. G ahead and select the desired ptin. 4. The tlkit will add the recrds t the Lucity Spatial cache and will be prcessed within the next 5 minutes by the Spatial Updater service n the Lucity Services server. Fr large amunt f data, yu may need t give it mre time t cmplete prcessing. Refer t the Trubleshting sectin f this help guide fr infrmatin n hw t track the prcess. Overview f Lucity Spatial (v2018 & 2018r2) 7
ArcMap Generating Live Wrk Layers After yu setup the Lucity Spatial Updater and the service has begun prcessing wrk lcatins yu are ready t display and interact with the results. The Lucity GIS extensin in ArcMap prvides sme ut-fthe-bx tls t facilitate the generatin f layers that can be used t shw the wrk lcatins. 1. In ArcMap n the Lucity tlbar, click n the buttn. The fllwing pp-up will appear: 2. Select the type f wrk lcatin yu wuld like t create frm the drp-dwn list and Click OK. 3. The assciated tl will appear allwing yu t prvide further details specific t the type f wrk. Overview f Lucity Spatial (v2018 & 2018r2) 8
4. Fill ut the frm based upn the varius settings and ptins that are available. a. Nte: All request and wrk rder fields are available fr use in the resulting layer. T adjust which fields shuld be included in the results yu will want t check the Select which fields shuld be included in the resulting layer(s). Overview f Lucity Spatial (v2018 & 2018r2) 9
5. Click Display nce yu are ready t generate the layers. Once the tl has cmpleted prcessing, the resulting gruped layer will be added t the map. Examining the resulting layers: The tl will generate 4 layers: Pint layer fr address and x/y data Pint layer fr asset data Plyline layer fr asset data Plygn layer fr asset data Ntes: Overview f Lucity Spatial (v2018 & 2018r2) 10
General- The resulting layer name and descriptin is determined by the user specified settings that were defined n the Lucity Spatial Views frm. Nte: The Descriptin will start with LucitySpatialWrk: r LucitySpatialRequest:. Yu can mdify the descriptin, but the descriptin must start with these key wrds. This is a requirement if these layers are t be used in the Lucity Web Map. Surce- The surce used fr the wrk layers is the Lucity database. The tl cnnects t the Lucity database as Lucity_User. Yu will need t knw this infrmatin if yu wish t publish the layer as a service later. Overview f Lucity Spatial (v2018 & 2018r2) 11
Symblgy- The default fr the tl is t symblize based upn the Wrk Categry Text (RQ_CAT_TY, WO_CAT_TY). The symblgy can be altered by ging t the layer s symblgy tab. Nte: The symblgy is nt dynamic. In ther wrds, if a new wrk rder/request is created that as is assigned t a categry that hasn t been used yet- it will nt shw in the layer. T accunt fr this situatin: Adjust the symblgy t include the <All ther values>. Even thugh yu visually wn t be able t tell what wrk categry the wrk item has been assigned, at least it will be visible in the layer. Occasinally yu will want t update the symblgy f the layer by using Add All Values. Ntes: Overview f Lucity Spatial (v2018 & 2018r2) 12
Definitin Query- A definitin query was applied t the layer if the ptin t use an existing filter r an advanced filter was specified n the Lucity Spatial Views Frm. Time- If the ptin t enable time n the generated layer was set, then the Time tab n the resulting layer will have sme additinal settings that can be cnfigured. Custmizatins t the layer settings (symblgy, labelling, etc) can be saved and used as the default fr future runs f the Lucity Spatial View tl. Fr mre infrmatin n hw t save these settings refer t the Lucity Symblgy default tl: http://help.lucity.cm/webhelp/v140/gis/index.htm#25859.htm The Lucity extensin tries t handle all the situatins needed with generating query layers; hwever, there may be sme additinal requirements needed based upn the underlying database platfrm. Refer t http://resurces.arcgis.cm/en/help/main/10.2/index.html#/preparing_t_use_query_layers/0 0s500000032000000/ fr mre infrmatin. Overview f Lucity Spatial (v2018 & 2018r2) 13
Publishing Live Wrk Layers After yu have created the live wrk layers, yu can distribute access t thse layers fr users n the ArcGIS Desktp platfrm. If yu wish t prvide access t thse layers in the Lucity web map, r any f the Lucity mbile applicatins then yu will need t create a map service that cntains these layers. There is mre than ne way t publish a map service; the fllwing is an example f hw yu can create the service frm within an ArcMap dcument (.mxd). In ArcMap add the live wrk layers t the map and custmize prperties s the map is displaying the data as yu like. In ArcMap, click File>>Share As>>Service. Befre yu publish the service, yu will want t analyse. The fllwing are sme cmmn warnings/errrs fund when publishing the Lucity Live Wrk Layers and hw they can be reslved: Layer s data surce is nt registered with the server and data will be cpied t the server i. This must be fixed; therwise, the layer will nt be refreshed with updates. ii. T reslve, right-click n the errr and select the Register Data Surce with Server ptin. Overview f Lucity Spatial (v2018 & 2018r2) 14
iii. If needed, yu may need t manually create a db cnnectin t Lucity using Lucity_User. Shape field is nt visible i. This must be reslved befre publishing ii. T reslve, right-click and select Make Shape Field Visible Once yu reslved all the issues, yu can publish the service. Once published, yu can add this service t the Lucity web map r mbile applicatins. The Lucity Live Wrk layers are essentially query layers. They are pinting t varius spatial views in the Lucity database. These layers are live meaning if a wrk lcatin is added/updated/deleted this infrmatin autmatically refreshed in the live wrk layer. Overview f Lucity Spatial (v2018 & 2018r2) 15
ArcGIS Pr Mdule Spatial Data Tl The Lucity Mdule Spatial Data tl in ArcGIS Pr allws a user t display Lucity Wrk data and inspectin data easily in the map. The Mdule Spatial Data tl lads spatial wrk/inspectin data int ArcGIS Pr with the fllwing steps: 1. Spatial features are returned t ArcGIS Pr frm Lucity. 2. LucityGISTls.gdb is created in the current Windws user s temp flder, if it desn t already exist. 3. Feature classes (fr each gemetry type returned) are created in the LucityGISTls.gdb. 4. Fields that the user specified t be included in the results are added t the feature classes. 5. The feature classes are ppulated with the spatial features frm Lucity. 6. The feature classes are added t the current map as layers. T use the Mdule Spatial Data Tl: 1. Click the Mdule Spatial Data buttn. The fllwing dialg will appear: Overview f Lucity Spatial (v2018 & 2018r2) 16
Selected Mdule: The mdule fr which t lad spatial features. This is set by clicking the Select Mdule buttn, which pens the fllwing dialg: Layer Title: The name t apply t the resulting layer(s) in the map. Filter: The filter used t retrieve spatial data frm the selected mdule. Change Filter: Enables the filter textbx s that the user may mdify the filter. Als displays a drpdwn list f current filters fr the selected mdule. Limit results t current map extent: Passes a spatial filter t Lucity s that nly features within the current map extent will be returned. Select Mdule: Cntrls which fields are shwn in the Select Field list view. This will either be the parent mdule, r ne f the child mdules. Select Field: Displays a list f all fields in the selected parent r child mdule selected under the Select Mdule list view. Clicking Add will add a field t the far-right list view, which hlds fields t be included in the results. Clicking Remve frm the far-right list view remves the field frm the list f fields t be included in the results. Clr cde based n field: Indicates that the resulting layers will be symblized based n unique values f a given field. If checked, the user must specify a field t symblize n and a clr palette t use. Symbl size: The symbl size fr pint/line features in the resulting layers. The default is 4. 2. Once yu have set the ptins t yur desired cnfiguratin, click Lad. While geprcessing tls are wrking t create and lad feature classes, a cancelable prgress indicatr is prvided: Overview f Lucity Spatial (v2018 & 2018r2) 17
3. Upn cmpletin, the resulting layer(s) are symblized and added t the map under a grup layer: Ntes: Overview f Lucity Spatial (v2018 & 2018r2) 18
Lucity Web Map Mdule Spatial Data Tl The Mdule Spatial Data tl enables users t display Lucity Wrk data and sme Lucity inspectin data in the map. The layers that are laded are a live view f the infrmatin in the Lucity database. Nte: The use f this tl requires that Lucity Spatial has been enabled and the service is running. 1. Click the Mdule Spatial Data tl 2. On the Lad Spatial Lucity Data frm, click the Select Mdule buttn. Overview f Lucity Spatial (v2018 & 2018r2) 19
3. Select a mdule and click OK. 4. Enter the Layer Title that yu wuld like t sue fr the layer this tl will create. 5. Click the Acquire buttn t select a filter. 6. Check the Limit results t current map extent ptin if yu wish t shw nly thse results that are in the current map extent. 7. In the Cnfigure Prperties t Include sectin, select any additinal fields that yu wuld like t include in the results. 8. Set a symbl clr and size 9. If yu want t use the clr cde based n field ptin, select a field and clr palette. 10. Click Lad 11. The spatial data will be laded in the map nce dne prcessing. Ntes: Overview f Lucity Spatial (v2018 & 2018r2) 20
Trubleshting Smetimes there may be recrds that fail t prcess. When a spatial change recrd cannt be prcessed it is kept in the Spatial Change table (Lucity.WKSPATIALCHANGE) and marked with an errr cde. These recrds are kept in the Spatial Change table fr 30 days after they were initially prcessed. After 30 days they are deleted. The errr cdes are fund in the SPCH_SU_ERROR clumn: MissingData Usually means that there was an issue with the data in WKSPATIALCHANGE like the mduleid is invalid; ParentRecID is invalid, invalid x/y data, etc. ServiceIssue This ccurs if there isn t a map service assciated with the feature class r the feature class related t the asset type is nt in the service NGemetry Returned if a recrd's gemetry was fund but was empty, if the indexer was unable t gecde an address, r if there was an issue with the REST call t retrieve the gemetry. NLucityRecrd Returned if the assciated recrd n lnger exists in Lucity Hw t Prcess Recrds that have failed: 1. In the WKSPATIALCHANGE table find the recrd that failed 2. Review the errr cde fr the recrd and reslve the prblem 3. Delete the cntents f the SPCH_GUID and SPCH_SU_ERROR fields fr the recrd 4. The next time the Lucity Spatial Updater service runs it will attempt t prcess the skipped recrd again. Overview f Lucity Spatial (v2018 & 2018r2) 21
Admin Prtal Tl The Lucity Web Admin Prtal cntains a sectin t shw the details f the Spatial Indexer Prcessing Queue. This is essentially the WKSPATIALCHANGE table as described in the Behind-the-scenes and Trubleshting sectins f this dcument. T view the prcessing queue: 1. Click the Open Admin Prtal tl in the Applicatin tlbar: 2. This will pen a new tab, titled Admin Prtal, expand the Web App Management sectin, and select the Spatial Updater Prcessing ptin. 3. This will pen the Spatial Indexer Prcessing Queue similar t belw: 4. Yu can review the infrmatin as needed. Refer t the Behind-the-scenes r Data Quality Tl sectins f this dcument fr mre infrmatin abut the data fund in this table and hw t reslve errrs. Overview f Lucity Spatial (v2018 & 2018r2) 22
Data Quality Tl The Lucity Data Quality Services Tl (DQS) was mdified in 2016r2 s there is nw an ptin t run queries n the wrk spatial tables. In additin, there is an ptin t fix the issues fund. Nte: This functinality is currently nly available fr SQL Server database clients. The DQS tl queries the Lucity spatial tables (WKGEOMPT, WKGEOMLN, WKGEOMPG) fr the fllwing data prblems: Features f a different gemetry type than what is suppsed t be in the table (i.e. pints in the plygn table). This is marked as an errr because this will cause prblems with functinality. Features where the spatial reference des nt match that f the Operatinal WKID as listed in Lucity system settings. This is marked as a warning because this may impact certain functinality. Features that have invalid gemetry (i.e. lines that intersect themselves, incmplete plygns, multiple vertices n tp f each ther, etc.). This is marked as an errr because this will cause prblems with functinality. The queries are in a new query suite titled Spatial and wrk the same way as ther queries in the prgram: Overview f Lucity Spatial (v2018 & 2018r2) 23