Overview

We recently added several Applicable Type endpoints to the Web API: https://announcements.alloyapp.io/applicable-types-now-enforced-by-web-api-3jpgbe

Applicable Types define how items of various activity-related designs can link to each other, e.g.

• Which Asset types can each Job/Inspection/Defect type be linked to?
• Which Job types can each Job Work Unit type be linked to?

When using the api/applicable-type/applicable-from endpoint, you may receive some unexpected results. Put simply, this is because the current logic is finding links that can be applicable but haven’t explicitly been made applicable.

To improve this, we’re changing how the endpoint behaves. Rather than accepting a list of designs, it will instead accept a list of items. The new logic will be able to use the parent or child items to determine which DoDIs or items are applicable from that item.

This should produce results that are more in line with expectations! However, it will require some breaking changes. 😐

Who will be affected?

These breaking changes will affect anyone who uses the ApplicableTypes endpoints on the Web API.

Details

New Endpoint Addresses

The addresses of the following endpoints will be changing.

List Applicable From Types endpoint

The request for this endpoint (ApplicableTypeFromWebRequestModel) will be changing:

• The toAll property will be removed.
• The from property will no longer accept a ApplicableFromItemWebModel (item IDs) and therefore will no longer require a discriminator. It will only accept ApplicableFromDodiWebModel (DoDi codes).
• The toAllItems required property will be added (to replace toAll). This is an array of item IDs that you wish to check.
• The filterAttributeCode required property will be added. This specifies the link attribute to find applicable types on. The attribute must be present on all the items provided in toAllItems.

For example, to query which job types can be raised against specific assets, you would provide these values for the aforementioned parameters:

• ToAllItems = an array of asset item IDs
• FilterAttributeCode = attributes_tasksAssignableTasks
• From = designInterfaces_jobs
  (to exclude inspections and other task types)

Additionally, the response model for this endpoint (ApplicableTypeFromWebResponseModel) will also be changing:

• The NoRestrictions property will be added.  If no results are returned, this boolean explains why. If true, there are no restrictions, which means everything applies. If false, it means that nothing applies.
• The results can be of type ApplicableFromDodiWebResponseModel or ApplicableFromItemResultWebModel, so these are the new discriminators to use (no more ApplicableItemWebModel).

Importantly, this revised endpoint won’t support finding applicable job types for supplied work unit items. This will be handled by a new endpoint coming in future.

List Applicable To Types endpoint

The response for this endpoint will be changing:

• The results can only be of type ApplicableToDodiWebResponseModel. Therefore, it will no longer be necessary to supply a discriminator.

Expected Release

8th December 2022 as part of the Alloy v2.42 release.

The documentation available on Swagger and ReDoc will be updated accordingly.

Overview

This is a follow-up to a recent post about an issue affecting the import of geometry data in Alloy Web.

The issue was caused by a third-party service (espg.io), which provided Alloy with a list of Coordinate Reference Systems (CRS) and the corresponding proj4 strings required for converting the incoming geometry data accordingly. Upon discovering the issue, we quickly issued a temporary workaround.

To avoid this situation repeating in future, we’ve now removed this dependence from Alloy in favour of a curated local list.

Who will be affected?

This change affects all users who use Gateway to import geometry data in Alloy Web.

Details

When configuring an import in Alloy, there are two optional steps in the procedure that involve imported geometry:

• Attributes – in this step, you can map headers in the incoming data to attributes on the selected design. After selecting a GeoJSON attribute, you can select the Coordinate System field and choose one from the list (see below).
  
  
• Geometry – in this step, you can specify the type of geometry data to be imported. After selecting a Type, you can select the 🔍 icon in the Coordinate System field and choose one from the list (see below). Unlike the previous step, the full proj4 string will appear in the field, so it can be edited if necessary before selecting Done.

The coordinate system will default to WGS84 Lat/Lng if not explicitly set.

If you have any existing imports that include geometry data and have a Status of Configured or Validated, we recommend reconfiguring them. To do this, open the import item, select More in the bottom action bar and choose Reconfigure.

Available Coordinate Systems

We’ve included the most popular coordinate systems to choose from. Any others we should add? Please feel free to contact Support with your suggestions!💡

OSGB36 / British National Grid
SRID:27700
+proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 +x_0=400000 +y_0=-100000 +ellps=airy +towgs84=446.448,-125.157,542.06,0.15,0.247,0.842,-20.489 +units=m +no_defs

WGS84 Metres
SRID:3857
+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null +wktext  +no_defs

WGS84 Lat/Lng
SRID:4326
+proj=longlat +datum=WGS84 +no_defs

NZGD2000 / New Zealand Transverse Mercator
SRID:2193
+proj=tmerc +lat_0=0 +lon_0=173 +k=0.9996 +x_0=1600000 +y_0=10000000 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs

Expected Release

Due to this new feature’s importance, it was hotfixed into the current Alloy v2.40 release on 17th October 2022.

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/), the logic performed when creating, updating and deleting job work units (work items and bill items) will be moved to the Web API (https://api.uk.alloyapp.io/).

This work is part of ongoing changes being made to functionality that has historically been available through the Extended API. Similar changes were made to defect logic (August), inspection logic (September) and job logic (September).

Who will be affected?

This change will affect any users who work with job work units 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 working with job work units:

• Through the Web API, where job work units are treated like any other item.
  
  
• Through the Extended API, where logic specific to job work units is applied when performing the same operations (e.g. limiting the types of parent a job work unit can have).

However, the way in which this additional logic was applied in the Extended API required a limit on the number of items being operated on, to guard against service degradation. Therefore, we're moving this logic to the Web API, so these limits can be removed in future.

As a result, there will be some changes to the behaviour of the Web API Item endpoints when a job work unit item is operated on.

Linking Jobs and Job Work Units

When creating or editing a job, it isn't possible to manually create links to corresponding job work units (or change an existing links).

This is because linking is handled automatically during other processes:

• When creating a job work unit, it will be linked to the parent job you specify.
  
  
• When a job work unit is deleted, the link to its parent job will be removed.
  
  
• When a job or job work unit is deep cloned, copies of both the job and job work units are created and linked together.

Job Work Unit constraints

A job work unit must be created with a link to a single parent job and a single work unit. Attempting to create one these will result in a BadRequest Error 1657715843.

Previously, if a job work unit had a custom parent in addition to its parent job, it was possible to clone that custom parent via this endpoint (see ReDoc).

POST /api/item/{id}/clone with cascadeModes set to Deep.

This would result in copies of the custom parent and job work unit being created and linked together. However, the job work unit would be missing the link to its parent job, which wouldn't be included in the clone operation.

This is no longer possible and will produce a BadRequest Error 1596183833 if attempted.

Automatic budget and estimated value

When creating a job work unit, if a budget or estimated value isn’t supplied, values for these will be copied from its linked work unit (if it holds any values for them).

Expected Release Date

8th December 2022 as part of the Alloy v2.42 release

Overview

When a staff member leaves an organisation, it’s common practice to disable any IT accounts used by them during their tenure. Currently, disabling an Alloy account requires you to contact our Support team.

However, it will soon be possible for Alloy Admins to disable/enable any account in their organisation!

After a user account has been disabled, the user’s name will remain visible throughout Alloy (e.g. in user lists, in team member lists). However, that user won’t be able to sign into Alloy Web or Alloy Mobile, nor will they be able to start a new session via the API.

Who will be affected?

These changes will affect System Admins who use the Web API to manage their organisation’s user accounts.

Details

A new User endpoint is being added to the Web API:

PUT api/user/{username} with request model CustomerUserEditWebRequestModel

If the enabled property is declared as false, the specified user’s account will become disabled.

The new endpoint’s documentation will be available on Swagger and ReDoc after release.

Expected Release Date

8th December 2022 as part of the Alloy v2.42 release.

The second update for September contains some useful improvements to Alloy Mobile iOS. The update was applied during the evening of the 29th September. For a full list of changes in v2.40, please visit the Alloy Changelog.

Note: the same functionality is planned for Alloy Mobile Android users.

Item Forms on Mobile iOS

In the previous update, we introduced item forms for Alloy Web. This new feature makes it possible to customise the form that users fill in when creating or editing items of a particular design/interface. For more information, see Alloy September 2022 Update.

In this update, item forms are now supported on Alloy Mobile iOS.

If a custom item form exists for a design/interface, it will be displayed to users automatically when creating or editing a corresponding item. As a result, users will only see attributes that the item form has controls for, displayed in the order defined by the item form.

If multiple item forms exist for a design/interface, Alloy will choose the one most relevant to the user’s situation. For example, an item form tagged as Mobile will be prioritised over one tagged All platforms.

If no custom item forms exist for a design/interface, Alloy will display the standard view (all attributes in stencil or creation order).

Prevent Locked Items Being Edited on Mobile iOS

In Alloy Web, items can be locked to prevent them being edited. This can be done manually via the action bar or automatically via a workflow.

When locked items get synced to Alloy Mobile iOS, they will now display a visual indication of their locked status if you try to edit them.

It’s therefore no longer possible to edit a locked item’s attributes or add/remove any items associated with it, such as attachments, job work items, or related tasks.

Read-only View of Link Attributes on Mobile iOS

If an item has a Link attribute that references multiple items (e.g. a job with multiple job work items), the attribute’s field will show X selected when the item’s details are viewed in Alloy Mobile iOS.

Tapping the attribute will display the list of linked items.

Previously, it was only possible to do this if the attribute was writeable. Therefore, if your user account only had Read only permission to the attribute, or the attribute’s Read only property was enabled, you couldn't see the linked items.

This has now been resolved, so tapping a Link attribute will always display the items it links to.

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), the logic performed when creating/updating/deleting jobs will be moved to the Web API (https://api.uk.alloyapp.io).

This work is part of ongoing changes being made to functionality that has historically been available through the Extended API. Similar changes were made to defect logic (August) and inspection logic (September).

Who will be affected?

This change will affect any users who work with jobs 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 working with jobs:

• Through the Web API, where jobs are treated like any other item.
• Through the Extended API, where certain job-specific logic is applied when performing the same operations (e.g. limiting the number of asset parents a job can have).

However, the way in which this additional logic was applied in the Extended API required a limit on the number of items being operated on, to guard against service degradation. Therefore, we're moving this logic to the Web API, so these limits can be removed in future.

As a result, there will be some changes to the behaviour of the Web API Item endpoints when a job item is operated on.

Application of Special Parent Logic

When creating or editing a job via the Web API, if no geometry is supplied, geometry from the job's parent asset will be copied to the job.

However, this won’t happen if the parent asset is through a path more than two hops away (e.g. a job raised against a defect that’s already linked to the asset). In such cases, the geometry from a parent non-asset item will be copied instead.

Required Geometry from Parent Items will not be copied

If Geometry is required by the job's design, then specific geometry must be supplied to the Web API during any operation.

Previously, the Extended API would automatically copy geometry from the job’s parent item. This won’t happen when using the Web API.

Therefore, if you do want the job’s geometry to be copied from the parent (asset or activity), we recommend leaving Geometry as optional (as per the Tasks interface).

Removing Job Geometry will force a re-fetch from the Special Parent

When editing a job, removing its geometry will cause the Web API to copy the geometry from its parent item again.

This means it's effectively impossible to set a job's geometry to null if it has parents with geometry.

Extended Logic will appear as another entry in Item Audit Logs

Previously, any extended logic performed on a job item would be included in a single edit record in the item’s audit log.

Following this change, extended logic operations will be logged 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 error handling in any existing integrations.

Jobs can only have One Asset Parent Enforced

Previously, jobs 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 the detail being ItemParentsContraintViolated instead of InternalError or DodiConstraint.

It was also possible to create jobs with multiple asset parents by creating them through the Web API instead of the Extended API. This will no longer be possible, as the same constraint will apply to the Web API Items endpoints.

No Automatic Raised Time

If no time is supplied for attributes_tasksRaisedTime when creating a job, the Extended API will automatically set it to the current date/time.

This functionality is planned for the Web API but isn’t available yet.

No Automatic Team Assignment 

If no team is supplied when creating a job, the Extended API will copy the default team from the parent asset (if set).

This functionality is planned for the Web API but isn’t available yet.

Expected Release Date

27th October 2022 as part of the Alloy v2.41 release

It's been over two years since our new alloyapp.io domain became the default for Alloy users. Since then, we've been redirecting from the old alloy.yotta.co.uk  and alloy.yotta.net.au domains to uk.alloyapp.io and au.alloyapp.io respectively.

Traffic monitoring shows us that there's been very little activity on these for a while now, which means you're all using the new URLs! Therefore, the redirects will be retired on 16th October 2022.

This change shouldn't affect any Alloy users, but if you have any of the old URLs saved as a bookmark or in a document somewhere, please update them!

We'd like to take this opportunity to say a big thank you from everyone on the Alloy team for continuing to join us on this journey 👍🏼

Overview

When using workflows to process large numbers of items, performance can start to become a limiting factor. To give you more control over how workflows are performed, you can now choose whether workflows operate in Single Item or Multiple Item mode.

Typically, a workflow that outputs a single item is easier to work with. However, when there are thousands of items to process, running thousands of corresponding workflows can get a bit slow!

In such situations, processing multiple items in a single workflow provides a huge performance boost, which is typically worth the price of having the workflow output all the items at once.

The current behaviour is as follows:

• Event workflows – a workflow is performed for each item.
  
  
• Manual workflows – a single workflow performs on all items passed to it (10,000 items max).

The upcoming changes essentially give you the option of swapping these behaviours if desired.

Who will be affected?

The changes will affect any users that create and edit workflows via the Alloy API. The new properties described below will eventually surface in Alloy Web.

Details

Event workflows

A new optional property outputMode will be added to the EventTrigger on the Workflow Create (ReDoc) and Workflow Edit (ReDoc) endpoints. The default value is OneItem.

When set to ManyItems, the event workflow will run with as many items as possible on its trigger node (depending on the item collection/event type). The performance will be orders of magnitude faster then processing the equivalent workload in OneItem mode.

Expected Release Date – 29th September 2022 as part of the Alloy v2.40 release.

Manual workflows

A new optional property WorkflowManualTriggerOutputMode will be added to the ManualTrigger on the Workflow Create (ReDoc) and Workflow Edit (ReDoc) endpoints. The default value is ManyItems.

When set to OneItem, the manual workflow will run once for each item passed to it. For example, if a workflow creates an invoice when supplied with an account's Item Id, the workflow will run once for each account, thereby generating an invoice for each one. It wouldn't be possible to do this in ManyItem mode.

Expected Release Date – 27th October 2022 as part of the Alloy v2.41 release.

Note: Due to a technical issue, this change was made to the Web API before the announcement was made. We wish to apologise for any inconvenience this has caused.

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/), the logic that's applied to inspection creation/updating/deletion will be moved to the Web API (https://api.uk.alloyapp.io/). This work is part of ongoing changes being made to functionality that has historically been available through the Extended API. This work is similar to the changes made to the defect logic in August (Defect Logic Announcement).

Who will be affected?

This change will affect any users who work with inspections 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 inspections:

1. through the Web API, where inspections are treated like any other item
2. through the Extended API, where certain inspection-specific logic is applied when carrying out the same operations. For example, limiting the number of asset parents an inspection can have, and applying relevant date values such as Raised Time.

However, the way in which this additional logic was applied in the Extended API required a limit on the number of items being operated on, to guard against service degradation. Therefore, we're moving this logic to the Web API, in order to remove these limits in the future.

As a result, there will be a few changes to the behaviour of the Web API Item endpoints when an inspection item is operated on in the following ways.

Application of Special Parent Logic

When creating or editing an inspection, geometry from the inspection's parent asset will typically be copied to the inspection if no geometry is supplied.

However, this will not happen if the parent asset is through a path more than two hops away (such as an inspection raised against a defect 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 inspection 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 inspection. This will not happen when using the Web API.

For activities where you would like the geometry to be automatically set to that of the parent (asset or activity), we recommend that Geometry is left optional (as per the Tasks interface).

Removing Inspection Geometry will force a re-fetch from the Special Parent

When editing an inspection, removing its geometry will cause the Web API to re-fetch the parent item's geometry and set the inspection's geometry to that. This means it's effectively impossible to set an inspection's geometry to null if it has parents with geometry.

Extended Logic will appear as another entry in Item Audit Logs

Previously, extended logic applied to inspection 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 error handling in any existing integrations.

Inspections can only have One Asset Parent Enforced

Previously, inspections 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, it was previously possible to create inspections with multiple asset parents by creating them through the Web API. This is now no longer possible, as the same constraint will now apply to the Web API Items endpoints.

No Automatic Raised Time

If no time is supplied for attributes_tasksRaisedTime when creating a job, the Extended API will automatically set it to the current date/time.

This functionality is planned for the Web API but isn’t available yet.

No Automatic Team Assignment 

If no team is supplied when creating a job, the Extended API will copy the default team from the parent asset (if set).

This functionality is planned for the Web API but isn’t available yet.

Expected Release Date

1st September 2022

We’ve got some exciting new features to showcase in this month’s Alloy update! The release will be applied during the evening of 1st September 2022. For a full list of changes, please visit the Alloy Changelog.

Item Forms

This is a big one! We’re pleased to announce that you can now customise the form that users fill in when creating/editing items.

Item forms can be created for any design/interface and provide a wealth of ways to customise data entry, which can improve save time and improve efficiency.

Using the new Item Form builder, you can add attribute controls to your form. Start with a blank canvas and add controls as required, or start with the default controls and remove as required.

Either way, Alloy warns you if the form is missing a control for a required attribute, and you can fix it with a single click.

Some things you can do with the Item Form builder are:

• specify the order of attributes
• show or hide an attribute
• make an optional attribute required
• override an attribute’s default value
• make an attribute read-only
• use AQS to sort and filter items in the lookup list of a link attribute

If this reminds you of stencils, there are indeed some similarities! However, a stencil customises how an item looks when viewing it, whereas an item form customises how data can be inputted into an item when creating/editing it.

Item forms aren't supported on Alloy Mobile just yet (users will see the default form instead) but this is coming soon.

Stay tuned for improvements and enhancements to item forms over the coming months!

Custom Interfaces

Another major new feature is the ability to edit interfaces and even create your own!

An interface is similar to a design but can be implemented by other designs/interfaces. This lets you define a group of generic attributes. Anything that implements the interface will inherit those attributes, as if they were their own.

For example, you could create a Playground Assets interface, which is implemented by more specific designs such as Swing and Slide. These will inherit the generic Playground Assets attributes alongside their own specific attributes.

Interfaces also provide a way to address multiple designs/interfaces at once. This is useful when working with things like:

• map layers
• AQS queries
• workflows
• reports

Targeting one interface instead of multiple designs saves you time and avoids repetition. Additionally, any future designs can be included by simply implementing the target interface, avoiding the need to go back and edit things.

We’re looking forward to seeing how everyone uses this powerful new feature!

Colour-coded Report Builder Controls

In the Report builder, controls now display a pill shape representing the control’s Label and Value fields. Pills are colour-coded depending on whether the field’s set value is dynamic (green), constant (blue), calculated (orange) or not set (white).

This gives you an indication of how your controls are configured at a glance. It also makes it a bit easier to set a control’s Label or Value, as you can now select the corresponding pill directly.

Bulk Trigger Manual Workflows

In May, we announced the ability to trigger a manual workflow for a single item. As of this release, you can now trigger a workflow on multiple items of the same type.

Select your items in Data explorer and perform a Bulk action as normal. Choose the new Trigger workflow option and select the desired workflow from the list.