Skip to content

Open311 FMS Service Definition additions

M Somerville edited this page Oct 7, 2024 · 5 revisions

Special keywords

If private is included in the keywords of a particular service returned by the GET Service List call, then it will be marked as non_public on FixMyStreet, which means reports made in that category will be automatically hidden from anyone except the reporter and staff.

Example

<!-- GET /services.xml -->
<?xml version="1.0" encoding="utf-8"?>
<services>
  <service>
    <service_code>BLOCKED_DRAIN</service_code>
    <service_name>Blocked drain</service_name>
    <description>Issues with blocked drains</description>
    <metadata>true</metadata>
    <type>realtime</type>
    <group>Flooding</group>
    <keywords>private</keywords>
  </service>
</services>

If staff is included in the keywords of a particular service, then it will be marked as a staff-only category on FixMyStreet, which means that during reporting that category will only be shown as an option to staff.

Service with multiple groups

FixMyStreet can also handle an Open311 service that, for a GET Service List call response, includes multiple groups for a particular service by looking for a groups element containing one or more group elements.

Example

<!-- GET /services.xml -->
<?xml version="1.0" encoding="utf-8"?>
<services>
  <service>
    <service_code>BLOCKED_DRAIN</service_code>
    <service_name>Blocked drain</service_name>
    <description>Issues with blocked drains</description>
    <metadata>true</metadata>
    <type>realtime</type>
    <groups>
      <group>Flooding</group>
      <group>Drainage</group>
    </groups>
  </service>
</services>

Automated attributes in service definitions

FixMyStreet can handle an additional optional <automated> element to any <attribute> returned by a GET Service Definition call. This additional field can be either blank, or set to hidden_field or server_set.

hidden_field

If set to hidden_field, then the attribute will be output on the FixMyStreet website during the reporting process as a hidden input field with no label, rather than a visible one as is the default. This is meant for attributes where the expectation is that it might be filled in automatically with e.g. a selected asset or nearest road identifier.

Example

This example adds a site_code hidden field which could then, for example, be populated with the selected asset ID using some custom code in FixMyStreet.

<!-- GET /services/BLOCKED_DRAIN.xml -->
<?xml version="1.0" encoding="utf-8"?>
<service_definition>
  <service_code>BLOCKED_DRAIN</service_code>
  <attributes>
    <attribute>
      <automated>hidden_field</automated>
      <code>site_code</code>
      <datatype>string</datatype>
      <description>Site code</description>
      <order>1</order>
      <required>false</required>
      <variable>true</variable>
    </attribute>
  </attributes>
</service_definition>

server_set

If set to server_set, then the attribute is not output on the FixMyStreet website during the reporting process at all. This is meant for attributes where the Open311 sending process will automatically fill in the required information. Default processing exists for attributes with codes as follows:

Code Description
easting The report's easting co-ordinate
northing The report's northing co-ordinate
fixmystreet_id The report's FixMyStreet ID

Other fields can be added with custom processing; examples include the report title/description (if those are required separately; by default Open311 puts them together in one field), or the report's URL.

Example

This example shows how to enable the easting, northing and fixmystreet_id attributes.

With the below service definition in place, FixMyStreet would automatically include attribute[easting], attribute[northing] and attribute[fixmystreet_id] when doing a POST service request for that service.

<!-- GET /services/BLOCKED_DRAIN.xml -->
<?xml version="1.0" encoding="utf-8"?>
<service_definition>
  <service_code>BLOCKED_DRAIN</service_code>
  <attributes>
    <attribute>
      <automated>server_set</automated>
      <code>fixmystreet_id</code>
      <datatype>string</datatype>
      <description>FixMyStreet ID</description>
      <required>true</required>
      <variable>false</variable>
    </attribute>
    <attribute>
      <automated>server_set</automated>
      <code>easting</code>
      <datatype>number</datatype>
      <description>Easting</description>
      <required>false</required>
      <variable>false</variable>
    </attribute>
    <attribute>
      <automated>server_set</automated>
      <code>northing</code>
      <datatype>number</datatype>
      <description>Northing</description>
      <required>false</required>
      <variable>false</variable>
    </attribute>
  </attributes>
</service_definition>