Overview

As part of work to remove limitations to the number of items allowed in operations on the Extended API (https://extended.api.uk.alloyapp.io/), logic applied to defect creation, updating and deletion will now be added to the Web API (https://api.uk.alloyapp.io/). This is the first of many changes we will be making to functionality currently available via the Extended API over the coming months.

Who will be affected?

This change will affect any users who work with defects in Alloy as these changes will be introduced on the API used by both the web client and mobile apps.

Details

There have always been two routes to work with defects, either through the Web API, where defects are treated the same as any other item or through the recommended Extended API where certain logic, specific to defects, is applied when carrying out the same operations. The way in which this additional logic was applied in the Extended API  meant that limits to the number of items operated on needed to be put in place to guard against service degradation. Moving this logic down to the Web API is required to remove these limits in the future.

These changes will result in a few changes in behaviour of the Web API Item endpoints when a defect item is operated on in the below ways:

Application of Special Parent Logic

When creating or editing a defect, geometry from the defect's parent asset will be copied to the defect if no geometry is supplied in most situations. This will not be the case if the parent asset is through a path that is more than two hops away (such as a defect raised against an inspection that is already linked to the asset), in these cases, the geometry from a parent non-asset item will be copied.

Required Geometry from Parent Items will not be copied

If Geometry is required on the defect design, then specific geometry must be supplied to the API during any operation. Previously, the Extended API would automatically copy geometry from the parent item for the defect, this will not happen when using the Web API. We therefore recommend that for activities where you would like the geometry to be automatically set to that of the parent (asset or activity), that the Geometry be left as optional as per the defects interface.

Removing Defect Geometry will force Re-fetch from the Special Parent

When editing a defect, removing the defect's geometry will cause the Web API to re-fetch the parent item's geometry and set the defect's geometry to that. This means it is effectively not possible to set a defect's geometry to null if it has parents with geometry set.

Extended Logic will appear as another entry in Item Audit Logs

Previously, extended logic applied to defect items would be included in a single edit record in the item audit. Following this change, extended logic operations will be added as a separate audit record to the main operation that triggered the change.

Changed Error Codes

Since this is effectively new logic being introduced, any errors encountered will generate different Alloy error numbers than the same error before the changes. This may affect any error handling in any existing integrations.

Defects can only have One Asset Parent Enforced

Previously, defects created through the Extended API were only permitted to have one asset parent. Contravening this constraint would result in a server error (500) being thrown. This has now been changed to return a bad user request (400) with detail being ItemParentsContraintViolated instead of InternalError.

Also, previously it was possible to create defects with multiple asset parents by creating them through the Web API, this is now no longer possible as the constraint will now apply to the Web API Items endpoints.

Defect Raised Time

The most visible change will be when creating defects through the Web API, if no time is supplied for attributes_defectsRaisedTime this will be automatically populated to the current date/time.

Expected Release Date

25th August 2022

Overview

It's now possible for an item to display different Titles/Subtitles depending on which collection it belongs to. This is primarily intended to help you differentiate between template items and live items.

Who will be affected?

This change will affect:

• users who create designs
• users who create template items

Details

A template item usually contains a custom Title/Subtitle, often including variables that will be populated when a live item is created from that template. While this powerful customisation is useful, it can make distinguishing between templates and live items tricky!

Therefore, you can now specify multiple Title/Subtitle values in a design, and items will use the appropriate Title/Subtitle for the collection they're in.

This enables you to label your template items effectively, while ensuring live items created from those templates will use the intended Title/Subtitle. You could also do this for archived items.

To do this, use #if and #else conditions in your Mustache templates that reference specific collections. For example:

{{#if collection_live}}Live Item Title{{#else}}Some Other Title{{/if}}

You can also use #elif ("else if") to add more conditions. For example:

{{#if collection_template}}Template Title
{{#elif collection_archive}}Archived Title
{{#else}}{{attributes_streetLightingUnitsUnitNumber}}
{{/if}}

Expected Release Date

29th July 2022 as part of the Alloy v2.39 release

Overview

A new setting can be added to workspaces to determine how long audit logs should be retained. Any logs older than the number of days specified will be deleted. This does not affect backups. This is to allow for greater control over the amount of storage space being used within workspaces.

Who will be affected?

This change will primarily affect users who interrogate the audit logs and system administrators.

Details

Audit logs are now automatically removed by the Alloy engine depending on a retention policy setting applied to workspaces. This policy defines the number of days audit logs should be retained for. If this setting is not present, audit logs are not removed. This setting is being made available to allow for greater control over the amount of storage space a workspace uses on the Alloy server. Where a retention policy is not configured, the audit logs will be held indefinitely.

Currently, this setting can only be set by the support team. Please contact the support team if you wish to enable this setting.

Expected Release Date

30th June 2022 as part of the Alloy v2.37 release

If you have ever wanted to connect with other Alloy users, we have recently set up a great place to do just that! Alloy Community is a place for users to discuss how they're using Alloy, ask for help, get support with issues and to discover more information about Alloy's uses. Anyone can sign up to post and it is routinely contributed to by a lot of the people involved in building Alloy.

If you haven't had a look yet, why not check it out?

Alloy Community

Overview

An option to export data as either a CSV or ESRI SHP file was introduced to the API in v2.32. This choice was added to the request model for the Data Export endpoint via a discriminator. When this was initially introduced, the discriminator was optional and if not supplied, would default to CSV. Since v2.35 the discriminator is now required when making calls to this endpoint.

Who does this affect?

This change affects API users of the Export endpoint. Web users are not affected.

Details

The following endpoint:

POST /api/export

now requires a value passed for discriminator which can currently take one of two options:

• ShapefileExportWebRequestModel requests made with this model will return files as SHP.
• CsvExportWebRequestModel requests made with this model will return data as a CSV. 

Not providing a value will now result in an error being returned.

Expected Release Date

This change was included as part of the v2.35 release of Alloy on 5th May 2022. We would like to apologise for any inconvenience this has caused.

Overview

As part of ongoing improvements to the Extended API, we are changing the way we consider required attributes on creation of activities through the API. This change is being made to ensure consistency with other endpoints as to how what 'Required' means when considering attribute values being supplied to the API by the caller.

Who will be affected?

Any users of the Extended API who rely on the geometry of created activities being inferred from the parent Asset will be affected by this change.

Details

Currently, it is possible to create an activity such as a Job or Defect via the Extended API and not provide geometry despite the activity Design having the geometry marked as required since the geometry may be inferred from the parent Asset. This has created an inconsistency where required attributes are not actually required.  

In order to remedy this inconsistency, we are making a change to ensure that values for all required attributes are always supplied by the caller of the API. For simplicity, the end result will be:

Required means required 😀

For activities where geometry and possibly other attribute values are not supplied but computed by a service/backend process, these attributes should be marked as optional. This ensures data consistency in the event that the backend process is unable to compute an attribute value for any reason.

Avoiding a Breaking Change

As part of this change, we will be updating all activity designs, including custom designs where possible to mark the geometry as optional to ensure that any integrations that rely on the previous interpretation are not affected by this change in behaviour.

Expected Release Date

This change will be rolled out over multiple releases starting from the end of May 2022.

Overview

Following an internal review of the performance of the API, we are updating the API rate limits to separate limits per endpoint. 

Previously, a single API rate limit was defined as "sustained calls of over 100 requests per minute on any endpoint" and was controlled via direct disabling of the API key responsible. Following our recent announcement regarding API Rate Limit Responses, we will no longer disable API keys in this way. 

Who will be affected by this change?

This change will affect any users directly using the API. We've taken the precaution of monitoring usage across all customers over the last few months to understand if any will be affected by these changes. The handful of customers that are exceeding some of these limits have been approached directly so that they can resolve any issues before we roll out the changed limits. 

Details

We are moving from a single limit across all endpoints to separate limits by endpoint to better reflect the load placed on the system by each call. These limits have been set based on extensive performance tests and are designed to minimise the impact on API users. These changes will further improve the robustness of the system for all users. The limits are outlined in the table below and are with respect to a time period of 1 minute (60000ms):

POST

api/aqs/query

120

POST

api/aqs/join

120

POST

api/aqs/statistics

120

POST

api/bulk/generic

20

PUT 
POST 
DELETE

api/design

50

PUT
POST
DELETE

api/designInterface

50

*

api/file (See Note 1 below)

100

GET

api/item

300

GET

api/item-version

300

PUT
POST
DELETE

api/item

150

GET

api/item/*/graph

100

GET

api/item/*/parents

300

POST

api/item-log/item/*/reconstruct

100

GET

api/item-log/item/*

200

GET

api/item-log/design/*

200

GET

api/layer/*/*/*/*/network

2000

GET

api/layer/*/*/*/*/cluster

5000

GET

api/layer/*/*/*/*/basic

2000

*

api/route/*

50

GET

api/oauth-reply

100

POST

api/oauth-token-login

100

POST

api/sync

120

PUT
POST
DELETE

api/workflow

50

PUT
POST
DELETE

api/workflow/*/action

50

PUT
POST
DELETE

api/workflow-action-group

50

PUT
POST
DELETE

api/workflow-action-group/*/action

50

POST

api/(workflow|workflow-action-group)/*/action/parameters

10

*

api/(budget|change-component|defect|inspection|job|project|team|work-unit)

100

POST

api/extended/bulk

20

All other endpoints not specified above

1000

Overview

We are adding a new option to the Data Export endpoint which allow you to set the export format to ESRI SHP (Shape) file instead of the standard CSV export. 

Who does this affect?

This change will affect API users of the Export endpoint who require ESRI shape file output. 

Details

The following endpoint:

POST /api/export 

can now be used to specify the export type as ESRI SHP. Note that due to length constraints in the SHP format for field data, attributes values may be truncated in the exported files.

The endpoint now accepts two different request models:

ShapefileExportWebRequestModel requests made with this model will return files as SHP.

CsvExportWebRequestModel requests made with this model will return data as a CSV.

Both these models extend the ExportWebRequestModelBase model.

Note the the SHP format consists of multiple (3) files that will be returned on the Export File endpoint as a zipped bundle. 

GET /api/export/{id}/file

Expected Release Date

13th January 2022

Overview

We are adding an new option to the data Export endpoint which allow you to specify the projection to be used for Geometry data by providing the Proj4 string to use to convert over from WGS84 (Lat-Long)

Who does this affect?

This change will affect API users of the Export endpoint but will not modify the existing behaviour if the optional setting is not provided. 

Details

The following endpoint:

POST /api/export 

now accepts an optional string proj4 that may be used to convert geometry coordinates into the spatial reference system of your choice. This mirrors the optional Proj4 setting used during import.

Without the proj4 string, geometry is exported in WGS84 (Longitude, Latitude) coordinates.

There is a database of PROJ4 strings available for searching here https://epsg.io/

For example, for the UK British National Grid system, the Proj4 string is

+proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 +x_0=400000 +y_0=-100000 +ellps=airy +datum=OSGB36 +units=m +no_defs

Expected Release Date

13th January 2022

Overview

We are adding a new feature that will allow administrators to specify the specific method of authentication (such as Microsoft Online SSO) to use in order to access Customer Projects. 

Who does this affect?

This change will affect administrators who want to restrict their users to using a specified authentication method over the current choice of email/password or SSO options including Google and Microsoft. Note that these policies may only be configured using Alloy Forge so please contact the Support Team to change the way in which users access your project. 

Details

This change has introduced a new concept called "Customer Security Policy". In simple terms, this is an object contained in the Customer document that is meant to include information about customer choices in terms of security related "settings".

Currently the security policy only includes the accepted authentication method property. If set, a user can only create a customer session for a specific customer if that session is created through one of the accepted authentication methods. Normally a customer session is created by switching a master session to a customer session. This means the master session will need to have been created through one of the accepted authentication methods.

If the user utilises an authentication method not on the accepted list, an error message will be presented and the user returned to the logon screen to retry. 

The security policies may be set using the following Forge endpoints:

GET api/customer/{id}/security-policy - Gets the customer security policy for a specific customer

* PUT api/customer/{id}/security-policy - Edits the customer security policy for a specific customer

Expected Release Date

13th January 2022