LUCITY REST API. This manual covers the Lucity RESTAPI. Version: 2017r2

Transcription

1 LUCITY REST API This manual covers the Lucity RESTAPI. Version: 2017r2

2 CONTENTS WELCOME... 1 Installation and Configuration... 3 Basics... 7 Working with Data... 8 Formats (json, XML)...13 Special Requirements for XML...13 Errors...14 Expected return codes and behavior...15 Lists...15 Etags...15 Query Parameters...17 Special Functions...19 Getting Record Counts: $count...19 Getting pick lists: {PropertyName}/ and {PropertyName}/$count...20 Caching support on lookups...21 Special lookups...22 Getting a new empty object: $new...22 Getting metadata: $fields...23 Discoverability...23 Document attachments, uploads, downloads...26 Working with Existing Filters: $filters and $myfilters...29 Errors...29 Commands...30 Clearing Cached Data: $cache...31 Warnings and Conflicts...31 Getting live updates based on property changes made by an end user...37 Secure Fields...37 ObjectCanBeEditied,ObjectCanBeDeleted...38 SQL Injection Considerations Function Template - Wide Grids...39 Changes...41 Other Notes...42 INDEX...43 WELCOME

3 The Lucity REST API's allow agencies to write their own applications that can communicate with Lucity. Lucity provides a REST API and a Citizen REST API. Samples The manual contains many code samples that you are free to use. We also have more samples and C# serialization objects available on Github. To access these samples you will need a github account and will need to provide that account name to Lucity Support ( to request access. Past Helpguide Versions Version 2016r2 ( Version 2016 ( Version 2015r2 ( Version 2015 ( Version 2014r2 ( Help File Version 2017r2 2

4 INSTALLATION AND CONFIGURATION Installation Both REST APIs are available on the standard install media 3

5 The Citizen REST API is designed for customer facing applications and requires no authentication. contains features such as: It Creating new requests Viewing Existing Requests Attaching or uploading documents to a request Blocking view of Personally Identifiable Information (PII). It will not serve up any data that has been assigned as PII data. By default this includes things like requestors name, requestors address, requestors . Only serves data that has been marked publically accessible. Every request in Lucity has a flag that identifies whether it should be available for public query. By default all requests that were submitted through the Lucity Citizen Portal REST API have this flag turned on. Can auto re-project coordinates to and from your agency s operational spatial reference (useful when getting data submitted from 311 systems which use Bing or Google or other maps) More information about installing the Citizen REST API ( The REST API is designed for internal use applications (GIS, financial integrations, etc.). authentication and used Basic authentication to provide the credentials to the server. we recommend TLS with this application. Supports viewing data from many different Lucity modules Supports creating data in many different Lucity modules Supports updating data from many different Lucity modules Supports deleting data from many different Lucity modules It requires For this reason Adheres to the user s security profile. If a user is not allowed to delete a work order in Lucity, then they cannot delete the work order in the REST API either. Supports a wide range of meta data and extra endpoints that may be useful beyond simple Lucity modules such as : o o o Filters Field Meta Data GIS Configuration Data 4

6 More information about installing the REST API ( Configuration Several Configuration options are available through System Settings 5

7 Allow RequestNumber and queries to the Citizen Portal REST API without providing both parameters The Citizen Portal REST API supports special query parameters RequestNumber and which allow searching for existing public requests based on the RequestNumber and requestor address. By default, the API requires both parameters are provided because this protects against fishing for data. this system setting is turned on, someone can query a request based on request number or if designed. If Default Public REST WKID, Use an alternate coord system as the Default Coordinate System for Public REST calls The Default Public REST WKID allows you to specify that all requests coming in through the Citizen Portal REST API should be assumed to be in a certain coordinate system (for example, Mercator). ESRI documentation provides a full list of available WKID values. This system setting goes hand in hand with the "Use an alternate coord system as the Default Coordinate System for Public Requests" setting. Alternately, if some clients are inserting data using Mercator and some clients are using an alternate coordinate system, the client can include criteria in each call that tells the REST API what the coordinate system is. To do this, include a query param COORDSYS= MERCATOR or COORDSYS=LOCAL or COORDSYS=LATLONG. Block SQL for the Lucity Citizen Portal REST API This provides additional SQL Injection protection to the Citizen Portal REST API. By default this is true. It prevents a consuming client application from using the Filter query parameter (which allows SQL to be passed directly). Disable DOS protection By default, the REST APIs provide rudimentary denial of service (DOS) protection. If a single IP address makes more than 1000 requests in 10 minutes, the system will not accept requests from that IP address. The number of requests and the number of minutes is also customizable but must be done in the appsettings.config file on the server. The names of the app settings that are applicable are DOSREQUESTS and DOSPERIOD. The latter value is in minutes. To disable the DOS protection for the REST API, change the Disable DOS protection setting to TRUE in the Lucity System Settings. Maximum records to return This setting limits the total number of records that may be returned on any one REST call. By default, 10 records are returned, but the client can request more records. This system setting sets a cap on how many total records can be returned in one call. Use extension-less URLs allow prettier URLs if that is something you care about. By default URLs will be like this: 6

8 With this option set to TRUE the URL will look like this: BASICS The Lucity REST API uses GET, PUT, POST, and DELETE to perform a variety of actions on resources in Lucity. A resource can be a work order, it can be a list of work orders, it can be a work order task, it can be a hydrant, etc. The URL for the web services is composed of the server where it is installed (potentially an alias instead) and the virtual directory (also can be aliased). Or for example: (this is a live functioning link) The entry page includes a list of all of the available root level resources. There are LOTS of them: 7

9 The list goes on. Drilling into one of these resources will provide details on what can be done with that resource. Drilling into the individual help requires authentication, so the browser will prompt for a user name and password. This is your Lucity user name and password. A small snippet of the available actions is shown here: WORKING WITH DATA Getting Data using a browser This mostly proves the service can be reached. does provide troubleshooting help. There probably is no real life application here, but it 8

10 Unfortunately there is no pretty json option, but XML is available which renders better when viewing data like this: Getting Data using javascript There are many different methods of getting the data using javascript and a lot of helper libraries out there. These samples use jquery and one of the lower level functions called.ajax. Because of cross origin concerns, the jquery.support.cors variable is set to true so that jquery knows that it is okay to send an http request to a server other than the one serving up this web page. 9

11 Posting Data (creating data) using javascript Putting Data (updating data) using javascript 10

12 Getting Data using C# There are also several ways to make HTTP requests with C#. The following gets a list of requests and outputs it to the console window (it will show up as a mess of XML text). It will only return the 10 most recent requests. This is not ideal for working with the data, so a better way is to deserialize the XML into an object that you can work with. We can provide these basic objects to make it easier to work with the data client side. Here is an example partial object: 11

13 The objects we provide also include some attributes that assist with serialization not shown in the above clip. They are included in a series of C# projects (or compiled dlls) called Lucity.*.SerializationObjects. These objects are current as of whenever you downloaded them from our site. It is not necessary to update these client side objects with each release. You only need to update the objects if there is a new property you want to take advantage of in the new release. The following example uses WebClient instead of HttpClient and deserializes the data into a collection object and then binds a grid on a windows form to the collection. This is part of SimpleWindowsFormsWorkOrderSample in the DesktopSamples solution. Posting (Creating) Data using C# This example creates a Request object (available in the Lucity.Work.Serialization project or assembly) and serializes it posting the data to the server to create a new request. The results of the operation are written to a list box called Results. This sample is part of SimpleWindowsFormsWorkOrderSample in the DesktopSamples solution. 12

14 There are many more samples including asynchronous options and WPF available in the DesktopSamples Solution. FORMATS (JSON, XML) Two formats are supported with the REST APIs: json and xml. Each request must include the format in the query string of the url (the default format is xml, so technically it is only required for json requests). Returns data in json or Returns data in xml. For posting and putting (creating and updating) data, the format must be included both in the query string And in the Content-Type of the request header. content type for xml is "application/xml". SPECIAL REQUIREMENTS FOR XML The content type for json is "application/json" and the It is not necessary to include all properties on an object when posting. If you are using the Lucity serialization objects and serializing them that will just happen automatically, but if you are manually building XML it is perfectly acceptable to include just the properties you want to update or insert. For example, a request can be inserted with the following body: <Request><ProblemCode>test</ProblemCode></Request> Which will insert a new request with the problem code = test. What is required, however, is that whatever properties are included are listed in alphabetical order. Again, if you are using the Lucity Serialization objects this is irrelevant. 13

15 ERRORS The Lucity REST API tries to follow the HTTP standard for errors. could be returned: The following is a table of errors that 401 UNAUTHORIZED 403 Forbidden 404 NOT FOUND 400 BAD REQUEST If you get this prompt, most likely you did not provide credentials or your login session expired. The user does not have permission to perform that function. The requested record was not found or the client made a request to a URL that does not exist and should consult the help listing for available endpoints. For example contains the available endpoints for Work Orders. The client application requested something that the server considers invalid. This could be a problem in the formatting of the data sent to the server, it could be that the data sent to the server causes a rules violation (like an invalid problem code). 400 Errors will generally include a description of the problem. 500 This is a server error. Check the logs on the server for the reason for the error. Typically these errors will show up both in the rolling.log and in the event viewer on the web server. 412 PRECONDITION FAILED 405 METHOD NOT ALLOWED On a PUT or DELETE, if the client includes an If-Match header and the ETAG does not match with the current version in the database, this error will be returned. This protects from overwriting another user s data, but is completely optional and the client system is responsible for including the header if this behavior is desired. This is returned if the client has requested to do something we do not support. For example, if a user tries to delete a request using the Lucity Citizen Portal REST API. 14

16 EXPECTED RETURN CODES AND BEHAVIOR Return status codes and headers also follow HTTP standards. codes you will see developing with the REST API. The following are the possible return 200 OK 201 CREATED 204 NO CONTENT 304 NOT MODIFIED A GET request will return this code if there were no problems with the request. There will be returned in the body of the response. A PUT will also return this status code if it was successful and will return a copy of the object in the body of the response as it currently exists in the database (this might include data changed after calculations, additional defaults, etc.). A POST request that creates a new record will return this status code and will return the copy of the object in the body of the response as it currently exists in the database. A DELETE request that successfully deletes a record will return this status code. The body of the response will be empty. A GET response which includes an ETAG may return a 304 not modified if the object in the database has not been modified since the original ETAG was issued. LISTS All lists will have a trailing backslash (query parameters go after the slash however). List of work orders and a list of work orders that are in a designated filter For example: List of available code types for MainTaskCode ETAGS ETags are returned on all GET that return a single record as well as all PUT and POST requests. The system will respect ETags for GETS, PUTS, and DELETES. For example, if a GET on a single work order is issued and it includes a header with the following: If-None-Match: " a7c876b7e" 15

17 The Lucity REST API will check the version of the work order in the database, if it matches the version provided in this ETAG, the Lucity REST API will return a 304 NOT MODIFIED. For Updates, ETAGS can be used to make sure that one user does not overwrite another user s data. If, on a PUT, the following is included on the header: If-Match: " a7c876b7e" The Lucity REST API will only make the requested update if the version of the record in the database matches the provided ETAG. 16

18 QUERY PARAMETERS The following query parameters are supported (not all requests support all query parameters). these query parameters are optional. All of FILTER Filter string which should general include a table name. For example: Filter=WKREQ WHERE RQ_STAT_CD < 950 (provided un-encoded here for clarity) FILTERID Filter Id that should be used to filter the data. Each module has a list of canned or predefined filters that have been saved by users. This is the AutoNumber that represents that saved filter. These filters are available as a list that you can show users (See Special Functions). ORDERBY The property or field name that the data should be sorted by. This is the Autonumber property by default (descending order). For example: OrderBy=StatusCode+DESC TAKE Designates how many records should be returned. By default 10 will be returned. The max is limited based on the Lucity Administrator assigned max in Lucity System Settings (max is defaulted to 50). SKIP Designates how many records to skip. For example, to get the second set of 15 records, the Skip = 15 and the Take = 15. Skip MUST be divisible by Take. You cannot request Skip = 20 and Take = 15. This will result in a 400 Bad Request error. FORMAT format=json or format=xml. The default is xml. The address of the requestor. This only is available for the public REST API and is affected by a system setting. REQUESTNUMBER The request number. This is only available for the public REST API and is affected by a custom setting STARTSWITH Limits returned records to only records that start with the provided text. Only supported on limited endpoints (picklists mostly) NULLWRITES Used only on PUT requests. Controls how null values (or missing properties) are handled. By default missing properties or null values (or default values such as 0 for a non-nullable numeric) are ignored in the input. To override this behavior and force these null values to be set, pass NULLWRITES=TRUE. This means that if a property is missing or has a null value, the REST API will attempt to change that value to null on the server (if the property is writable). Do not use this option unless you are certain you will be sending up every property on PUT requests or you may end up overwriting real data. 311ONLY This parameter is used on problem picklists only and tells the application to only return problems that are marked for 311 in the problem setup module. PROPERTYID Used for limit lists for picklists. This property id is the id of the field on a submit form where a user has defined a limit list. IDLIST Filters the data to only items where the AutoNumber or unique Id are in the list 17

19 SELECTEDIDS provided. This is not a text field, it corresponds to the identity column in the dataset. This property in the response objects is always "Autonumber". Used only on GET requests. Used for tools to indicate which ids the tool should be applied to. PROPERTY Used on POST and PUT $nonpersistent requests only. Used to indicate the last field the user edited and is helpful for the server in figuring out what the object should look like after the user s edits. DOCDESCRIPTION Query parameter used when uploading new documents. Allows for a description to be set on the document. By default the document description is the date and time of the upload. WARN Indicates that the code should provide warnings (these will be returned as 409 CONFLICT responses). By default warnings are ignored in the REST API and will not be returned for display to the user. STARTSWITH This is a special query parameter only available for certain lookup lists such as category, problem, or standard code type values. For example: STARTSWITH=a will return all code types where the code (and in some cases the type) starts with an a. COMMONID Allows for a query based on the common id of an asset. This is only supported in limited inventory and inspection modules. This corresponds to a text value which should be encoded in the request if there is any risk of spaces or special non alphanumeric characters may be used. INVALIDSTREETTOGENLO C This setting is used for the Public REST API. If there is a problem with the street name the user provided, that the value should be placed in the non-validated general location field. By default this is false. STATUSFLAG Supported for request and work order modules only. Allowed values are CLOSED and OPEN STATUSDAYS Works with the STATUSFLAG query parameter. Limits the data returned to only records whose status has changed in the last X days. By default the STATUSFLAG query parameter returns all records (up to the maximum take). COORDSYS This is a special query parameter only used with the Citizen Portal REST API. See documentation on configuration for a discussion on this parameter. Available options are COORDSYS=LOCAL, COORDSYS=MERCATOR, COORDSYS=LATLONG MODIFIEDSINCE MINE Allows you to request all records modified since a date/time. Tells the system only to return records created by the current logged in user. 18

20 SPECIAL FUNCTIONS The following sections go over how to perform special functions in Lucity web. GETTING RECORD COUNTS: $COUNT This keyword will always occur after a trailing slash and can include query parameters. total record count (with respect to the supplied query parameters). GET ( It will return the Returns a count of all work orders GET T_CD%3C950 ( _CD%3C950) Returns a count of all open work orders (where WO_STAT_CD < 950) GET ( Returns a count of all available code type values for MainTaskCode on a work order. 19

21 GETTING PICK LISTS: {PROPERTYNAME}/ AND {PROPERTYNAME}/$COUNT Getting pick lists: {PropertyName}/ and {PropertyName}/$count Fields that are pick lists (code types, problem codes, time codes, category codes, etc.) have a special endpoint that can return all of the valid pick list items. The format of the URL is the Child List]/[PropertyName] For example: ( Returns all available priority codes. 20

22 ( Returns all available unit of measure values for the tasks on work orders. Property names are case sensitive on these requests. Work flow code types (such as problem, cause, and task) also follow this convention. problems which can be assigned to a work order are at this endpoint: ( All available It is also possible to get a list of only the items associated to a specific category. ( Returns all main task codes associated to a category with category code = CACHING SUPPORT ON LOOKUPS Many lookups support caching using the traditional HTTP If-Modified-Since caching pattern ( For larger picklists (such as the street list or materials list), caching can improve response time. 21

23 SPECIAL LOOKUPS There are several special types of lookups in the system which have different requirements or return a different object than the standard lookups. The Category lookup ( ( or ( includes information required to re-construct a tree for the category. Other lookups in the system will depend upon the current state of an object and therefore require a POST request instead of a GET request and requre that the current object be provided in the body of the request. These are commonly referred to as Value Lookups. For example, in the water pipes module, the values for the FromNode depend upon the value of the FromNodeType. If the FromNodeType is a valve, the FromNode lookup will return a list of valves. If the FromNodeType is a hydrant, the list will be hydrants, and so on. GETTING A NEW EMPTY OBJECT: $NEW To get a new object with all defaults populated use the $new keyword. GET ( Returns a request object with all of the defaults populated (such as status code and any other custom defined defaults as well). This call makes no changes to the data on the server. 22

24 GETTING METADATA: $FIELDS To get metadata about fields such as the user defined display name, maximum mask, field type, whether it is required or read-only, use the $fields keyword. For example: ( Returns all of the properties and fields on a request and details about each field: DISCOVERABILITY The Lucity REST API provides a method for discoverability of actions on most endpoints (internal REST API only). Each object returned from the REST API includes a DataUrl. This data url is a link to a collection of actions which may be done with the current resource. 23

25 This is a sample: The above 2 action links tell you that you can View the work order (which you obviously already know), and tells you you can Edit the current object and provides the url and verb for each. This is a small portion of the list. Other items which may be included in this list include what children are available on the list and what you can do on the child items: 24

26 It may also include commands like this command available on a work request: And the url to use to get attached documents or attach or upload a document: 25

27 DOCUMENT ATTACHMENTS, UPLOADS, DOWNLOADS Lucity offers two ways of attaching a document to a record. It can be attached, which means that the user has manually copied it out to a file share somewhere and we store the path to the document. This works well for existing documents where the user has read/write permissions to the place where the document is loaded and when the share is available (the user is in the office and is not out in the field on a remote device like an ipad). Alternately, documents can be downloaded and uploaded to and from the server. This is effective if the client device does not have direct access to the file share or if the user does not have read (or write in the case of upload) permissions to the directory where the file is being uploaded. Before attempting to get upload and download functioning in the REST API, it is strongly advised that the client make sure that document upload and download is working in Lucity Web. It is much easier to troubleshoot problems with upload and download configurations in the Lucity Web application. The action links provides information for how to do both options. Add Document allows a new item to be added with a path to an existing document someplace. Upload Document allows a document to be streamed to the server (the server will persist the document on a file share designed by an administrator). If you know that you will always be uploading to a single module like TV Inspections, you can easily figure out the url without using action links. You would need to get the module Id for TV Inspections and you will need the AutoNumber of the TVInspection you want to attach the document to: Adding a document: server/virdir/documents/{moduleid}/{autonumberofrecorddocumentisbeingattachedto/ Uploading a document: server/virdir/documents/{moduleid}/{autonumberofrecorddocumentisbeingattachedto/media / If you attempt an upload greater than the maximum size, the server will return a 413 (Request Entity Too Large) or a 400 (Bad Request) This is what a typical upload looks like: 26

28 To get a list of existing documents and get the path or download the documents, you can use the action links (View Documents) or construct the url if you know the module id and AutoNumber: Notice that this document provides general information about the document (description, who last modified or inserted the document). It also provides a DataUrl. The data url provides what can be done with this attached document. For example, can it be edited, can it be viewed, can it be downloaded and the urls and verbs for each of these actions. In the case of the above document, it is a web page link and therefore does not support a download option 27

29 This is another document which represents a physical file: The action links for the above document includes Download Document 28

30 WORKING WITH EXISTING FILTERS: $FILTERS AND $MYFILTERS To let a user pick from a list of existing filters, use the $filters and $myfilters keyword. supports query parameters StartsWith, Skip, and Take. For example: ( This keyword Returns all Work Order filters for the currently logged in user ( Returns all Work Order filters for all users ( Returns a count of all filters available for the currently logged in user ( Returns a count of all filters for the currently logged in user that start with A. and the following syntax returns these filters ( ERRORS Most 400 series errors are caused by user error. In most cases, the system will return a user friendly message for user errors. For example, if I try to create a work order without the required data: 29

31 Client applications should always try and deserialize this information for display to a user or for logging. In some cases the error will not follow this format. For example, performing a post without Content-Type specified will return this rather unfriendly error: This type of error is generally only returned due to developer error (not user data entry error). COMMANDS The REST API supports commands for certain actions like creating a work order from an asset or from a request. Commands always use a POST verb. They return 200 OK if they succeeded and will return a CommandResponse which may include the Url of the returned object as well as any messages that may be relevant for the user. Commands can be discovered using Action Links. They also typically follow a url pattern, so if you already know exactly what you will be doing and the only variance will be which record you want to run the command on, you may be able to mostly hardcode the url. This is the command for creating a work order from a request from the request action links: The url format is: Server/virdir/Work/Tools/CreateWorkOrder?ModuleId={moduleId}&IdList={commaDelimListOfIds ForCommand} The moduleid for requests is 50, the above screen cap shows the url for creating a work order from a request with an AutoNumber = No body is required for this request. The response will be a CommandResponse: 30

32 This is a succesful response which provides the data url to the newly created work order. Here are some of the tools that you may be interested in: Creating a work order from a request Creating a work order from an inspection (this links the inspection to the work order). Creating a work order or a request from an inventory record CLEARING CACHED DATA: $CACHE Lucity caches certain data to make lookups faster and to reduce the load on the database server. includes things like pick list values, field properties, as well as others. The REST APIs are stateless web service applications. Restarting the app pool will not upset current users other than causing a very small delay the next time a request is made. However, restarting the app pool is not always realistic and is not possible directly from a client application. It is possible to force a cache to clear on the REST API server from a client application using the $cache keyword and the DELETE method. DELETE ( Will clear the caches that are associated with the Work Order objects. This should return a 204 NO CONTENT if the cache clear was successful. WARNINGS AND CONFLICTS Sometimes saving information generates a warning in the Lucity software, or generates a requirement for more information (like what warehouse should we take the parts from). By default, the system will not show any warnings and will just ignore them and allow the save. For parts inventory, by default the system will automatically figure out from where to disburse parts. To have the REST API return warnings or parts inventory prompt information, the following header should be included in the request LUCITYSF:[a comma delimited list of special features] Currently 2 types of special features are supported This 31

33 To have the system return warnings but not parts prompts, the header provided should be: LUCITYSF:1 To have the system return both parts prompts and warnings, the header provided should be: LUCITYSF:0,1 When this header is passed, the Lucity REST API may (if required), return a 409 CONFLICT instead of a 200 OK or 201 CREATED. 409 CONFLICT indicates that the server cannot proceed without additional input because of a conflict with the data. The 409 CONFLICT responses will include a body which tells the client application how to get the additional information it needs and how to resubmit the request. All 409 conflict responses share the same basic information. This is a flow diagram showing how conflict responses should be addressed: 32

34 This is what a conflict response looks like An Actual Response showing data: 33

35 34

36 When you get a 409 conflict, you should extract the list of conflicts from the response as well as the object. You should show the user a series of prompts (one for each conflict). For parts inventory these prompts will always be "Choice" prompts, which means that the response will include a message as well as a list of choices for the user to select. We recommend providing a cancel option too which allows the user to abandon the attempt. If a request returns a 409 conflict response, and the ChoiceType = "OK" then the conflict is a warning. Warnings are dealt with similar to parts inventory, but they are simpler. There is a message to display to the user and there are no choices except OK and CANCEL. There may be more than one warning returned in the Conflicts list. acknowledged in order to successfully save. Re-submit All warnings need to be Once the warnings are acknowledged (and not canceled), the application should attempt to re-submit the request and include the lucityconflict header in the new request. The conflict header should look like this: lucityconflict:warranty:ok,availability:ok Where Warranty was the conflict Id for the first conflict and Availability was the Id for the second conflict. Alternately, the request could be re-submitted without the LucitySF header to avoid the conflict response. Examples: This is the conflict response (shown in a tree view to make it more readable, the actual response returns XML) that might be returned if an asset is added to a work order and there is already another open work order with that asset This is the plain text view: 35

37 The user should see something like: BGB0532 is already attached to the following open Work Orders: Work Order ID: 5140 Work Order ID: 5993 Work Order ID: 6170 Work Order ID: 6322 Work Order ID: 6323 Work Order ID: 6433 Work Order ID: 6480 Work Order ID: 7257 Work Order ID: 7272 Work Order ID: 7274 Work Order ID: 7378 And: BGB0532 has at least one open warranty. Supplier: Manufacturer Warranty Type: 5 Year Warranty Open Date: 7/14/2011 Expiration Date: 12/1/2014 Review Date: In order to successfully re-submit for this example, the client application would need to include the following header in the request: lucityconflict:assetlinkingid:ok OR The client application could re-submit the request and exclude the header which tells the server to return warning conflicts. LucitySF:1 36

38 GETTING LIVE UPDATES BASED ON PROPERTY CHANGES MADE BY AN END USER It is possible to get updates for an object when the user changes a property. For example, if the user selects a problem on a work order, the server might automatically populate task, supervisor, priority, and other information based on that selected problem. These updates are done using a $nonpersistent specification in the url. For example, if the user is editing an existing work order with the Autonumber 123, the client application can make this request PUT e ( ) And include the current state of the request object in the body of the request. When the server receives this request, it will populate all of the relevant data based on the state of the object provided and will return the updated object to the client without persisting any data to the database. Additionally, responses from the $nonpersistent request include a property "BrokenRulesDisplayString" which will contain a user friendly message which lists all of the current validation problems on the object. For example, if the user has not yet provided a start date and the start date is a required field, the BrokenRulesString will include a note about the missing data. Another property returned is PropertiesThatAreDynamicallyReadonly. Sometimes the state of an object will affect which properties on an object are editable. For example, on work orders if a user says they want to use resource costing, the system will not allow the user to input manual task cost information (because it will be rolled up from the resource). It is important to note that the REST API will not throw an exception if the user edits this information, but it will ignore any data provided in these fields which may be confusing to an end user if they were allowed to input data. Only properties which have AffectsOtherProperties = true will benefit from this. in this document for how to determine which properties have this attribute. See $fields metadata SECURE FIELDS Lucity allows administrators to disable access to secure information on a user by user basis. Currently this is pay rates or anything that would allow a user to back calculate someone s pay. Responses which contain secure data will return if the current user does not have permissions to view secure data. 37

39 OBJECTCANBEEDITIED,OBJECTCANBEDELETED Responses returned from the REST API on editable objects contain two special properties ObjectCanBeEdited and ObjectCanBeDeleted which will identify whether or not the currently logged in user will be allowed to PUT or DELETE data for the current object. SQL INJECTION CONSIDERATIONS Allowing a client application to send SQL directly to the server for processing can impose a risk on the server. While Lucity endeavors to scrub all SQL for risky character sequences, it is difficult to completely eliminate the risk. There are several methods that can be used to further reduce SQL Injection risk with the REST API. The Citizen Portal REST API has a system setting which is defaulted to true "Block SQL for the Lucity Citizen Portal REST API". This will prevent any processes from making requests to the Citizen Portal REST API which includes SQL. If this request: GET ( ') Is made to the server with the "Block SQL for the Lucity Citizen Portal REST API" setting TRUE, the server will respond to the request with: An alternative to passing SQL is to use a precompiled filter with the "FilterId=" query parameter. the Working with "Existing Filters: $filters and $myfilters" section in this guide. However, these precompiled filters do not allow dynamic parameters. Alternately, other pre-built filters can be used such as: See StatusFlag and StatusDays RequestNumber and See the section on Query Parameters in this guide for more details on these query parameter options. Starting in Lucity 2015, the Lucity REST API will offer a system setting to block SQL as well. This system setting is "Block SQL for the Lucity REST API" which will default to FALSE. 38

40 FUNCTION TEMPLATE - WIDE GRIDS Within the Lucity Web > Admin Portal > System Settings ( there are REST API settings that allow administrators to configure the REST APIs. FIELD Allow RequestNumber and queries to the Citizen Portal REST API without providing both parameters Automatically push invalid request addresses to the general location field Default Public REST WKID Expose a service directory for Lucity Citizen Portal REST API Expose a service directory for Lucity REST API Logon to use for anonymous REST API Access Maximum records to return per request for rest api Send Stack Traces to Client Apps on Errors from REST APIs Url for Citizen Portal REST API (optional, rarely required) FUNCTION Controls how the Citizen Portal REST API works. Enable this option to allow the API to search for a Request using either the Request Number or address without having to have both parameter Allows third-party application developers to instruct the REST API to automatically move an invalid address made on a citizen Request to the general location field (if empty). This feature is helpful when citizens can enter an address which may not validate. It only applies to the Citizen Portal RE API. Specifies the WKID (well-known ID) for the coordinate system used by the external GIS service, if: and the external GIS service's WKID is different than the Operational Data Spatial Reference WKID found on the GIS Web tab; the external service is NOT using a Mercator projection. Determines whether a help page (directory) is included for the Lucity Citizen Portal REST API openin page. It is recommended that this setting be turned off in production environments because it expo unnecessary information about the endpoints and access points available. Determines whether a help page (directory) is included for the Lucity REST API opening page. It is recommended that this setting be turned off in production environments because it exposes unnecessary information about the endpoints and access points available. Allows anonymous users to gain access to Lucity. Limits the amount of records in a filtered set. server performance will be affected. Provides detailed information through the REST API. The higher the number, the more likely it is that we WARNING: THIS OPTION SHOULD ONLY BE SET TO TRUE FOR DEBUGGING PURPOSES, AS IT MAY REVEAL INFORMATION THAT HACKERS COULD USE TO ATTACK THE SYSTEM. Used by clients that have the Citizen Portal REST API installed behind a load-balancer that uses transport layer security (TLS), while the services behind the balancer use HTTP. Alternately, this setting may also be used by clients whose URL differs from the standard 39

41 URL for Internal REST API (required for internal web app) Url for REST API (optional, rarely required) Use an alternate coord system as the Default Coordinate System for Public REST calls Use Extensionless URL's (only supported in IIS7+) The URL for the Internal REST API used by Lucity Web. This URL is required to run the application. Used by clients that have the REST API installed behind a load-balancer that uses transport layer security (TLS), while the services behind the balancer use HTTP. Alternately, this setting could also be used by clients whose URL differs from the standard When enabled and the Default Public REST WKID is blank, the system assumes the incoming geographic information is using a Mercator projection. If the Default Public REST WKID is filled ou the system uses the specified WKID's projection. If this option is set to FALSE, the system assumes that any incoming geographic information uses th Operational Data Spatial Reference WKID found on the GIS Web tab. Allows administrators to choose to omit the extension in the REST API URLs. For example, if the URL is setting this option to TRUE would allow users to use the following URL instead: Note that the second URL does no include the ".svc" extension. 40

42 CHANGES Lucity 2016r2 Dates All dates are now returned in ISO8601 UTC format ( T16:43:36Z) ( Extensionless Endpoints We now support extensionless endpoints, such as Work/WorkOrder/1212/WorkOrderTaskList/. We continue to support the older style: Work/WorkOrder.svc/1212/WorkOrderTaskList/. Both styles will be supported for the next couple of releases; however new development should use the extensionless format. Eventually, the.svc format will no longer be supported. Routes Several routes have been moved: "/AssetCategoryList.svc/" is now "/Work/AssetCategoryList/". "/Documents.svc/" is now "/Shared/Documents/". "/System.svc/" is now "/Shared/System/". In the Part Vendors REST interface, the Description property was renamed to VendorDescription. The following routes will be removed in Lucity Alternate routes should be used. Shared/LookupList/ Serialization Object Namespaces The Lucity.SerializationObjects namespaces may no longer be included in XML submitted to the server. This restriction should not affect developers who started working with the API since January It may, however, affect REST API apps created before This does not affect applications using JSON. Service Directory The service directory can now be hidden, and is now hidden by default. Lucity recommends leaving the service directory hidden except for in test or development environments. Lucity 2016 Status Codes 41

43 When a user is not authorized to perform an action due to permissions, the REST API now returns a 403 Forbidden code. Previously, the system returned a 401 Unauthorized code. 401 is now used only to indicate a failure to log into Lucity or an expired login session. Lucity 2015r2 Added a Publicly Available property on Request records to indicate whether the Memo should be visible to the public. OTHER NOTES Launching the Lucity Web Application using a URL The following information is required to open the web software: lucityweburl: This is the url to the Lucity Web application moduleid: This is the module Id for the module you want to open. A comprehensive list of module Ids is available in the KeyId field of the Modules table in the GBAUser database. The module Id for work orders is 48. filterstring: This is the filter string for the module you want to open. For example, to open work order 1212 the string would be WKORDER WHERE WO_ID = 1212 tabname: This is a simple string that describes what you are showing. It is the tab name that is used when displaying the data to the user. This is the url: [lucityweburl]/public/routing.aspx?routetarget=internal&routesubtarget=views&routeaction=op endefault&routeparam1=[moduleid]&routeparam2=[tabname]&routeparam3=[filterstring] (*note that the above URL is not shown encoded. You may want to encode the URL) Example usage that opens work orders to a work order Id of s&routeaction=opendefault&routeparam1=48&routeparam2=my+work+order&routeparam3=wk ORDER+WHERE+WO_ID%3D1212&end=true ( s&routeaction=opendefault&routeparam1=48&routeparam2=my+work+order&routeparam3=wk ORDER+WHERE+WO_ID%3D1212&end=true) 42

44 INDEX FUNCTION TEMPLATE - WIDE GRIDS 39 B BASICS 7 C CACHING SUPPORT ON LOOKUPS 21 CHANGES 41 CLEARING CACHED DATA $CACHE 31 COMMANDS 30 D DISCOVERABILITY 23 DOCUMENT ATTACHMENTS, UPLOADS, DOWNLOADS 26 E ERRORS 14, 29 ETAGS 15 EXPECTED RETURN CODES AND BEHAVIOR 15 F FORMATS (JSON, XML) 13 G GETTING A NEW EMPTY OBJECT $NEW 22 GETTING LIVE UPDATES BASED ON PROPERTY CHANGES MADE BY AN END USER 37 GETTING METADATA $FIELDS 23 GETTING PICK LISTS PROPERTYNAME / AND PROPERTYNAME /$COUNT 20 GETTING RECORD COUNTS I $COUNT 19 INSTALLATION AND CONFIGURATION 3 L LISTS 15 O OBJECTCANBEEDITIED,OBJECTCANBEDELE TED 38 OTHER NOTES 42 Q QUERY PARAMETERS 17 S SECURE FIELDS 37 SPECIAL FUNCTIONS 19 SPECIAL LOOKUPS 22 SPECIAL REQUIREMENTS FOR XML 13 SQL INJECTION CONSIDERATIONS 38 W WARNINGS AND CONFLICTS 31 WELCOME 1 WORKING WITH DATA 8 WORKING WITH EXISTING FILTERS

45 $FILTERS AND $MYFILTERS 29 44