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

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.

Context

As you may be aware, we have been facing an issue with importing geometry data through the Gateway using the Alloy Web Client. Currently, when a coordinate system is selected, all rows with geometry in an import will return a warning and will not be imported correctly. This has been due to a change to a third-party service which supplies projection settings used by the Alloy Web Client.

This is an ongoing issue and has not yet been resolved, however, in an effort to allow a workaround for this issue, we have altered the coordinate system selection to display the conversion (proj4) string.

Workaround

To select your data file's coordinate system, click the magnifying glass icon to bring up the picker and select from the list.

This populates the Coordinate system text box with the configuration string for your selected coordinate system. This string is currently being formed incorrectly and removing the text +type=crs at the end of the string, will resolve this import issue.

We understand that this solution is not ideal, and are working on a long-term fix, but in the meantime, we have introduced this change to allow you to continue importing your data.

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

This month's release brings a few small, yet mighty changes to Alloy. Here's a quick run-through of the highlights of this release. If you would like to see the full list of everything included in this release, take a look at https://releases.alloyapp.io

Character Limit Removed from Defects Description

The Description attribute which appears on all Defects designs previously had a character limit which was just too low for most uses. As part of this release, we have removed this limit, allowing you to use the attribute to store much more detail about defects.

Locations of Interest

Included in this release of Alloy Mobile, is a shortcut method for navigating to your workspace's locations of interest. The menu bar now includes a Locations of Interest (LOI) option, which will bring up your LOIs in a drawer list. Tapping the location pin of an LOI in the list will open the location in available mapping applications on your mobile, allowing you to navigate to the location.

We envisage this helping with things like needing to navigate to a tip if you're on a waste collection round and need to empty a vehicle, or to navigate back to a depot. The list can also be sorted and filtered, as an example, for times when you may need to find the closest LOI.

This feature is currently only available on the Android version of Alloy Mobile, we hope to bring this feature to iOS soon.

Full-Screen Job Work Item Editor - Mobile

Also included in this release of Alloy Mobile is a new experience when managing your Job Work Items. A new widget has been added to represent Job Work Items on Jobs, it gives you more of an overview of estimated and actual values and makes it much easier to quickly enter these figures whilst on a job.

This feature is currently only available on the iOS version of Alloy Mobile, we will be introducing it to the Android version soon.

As an extra special treat, this month contains not one, but two Alloy updates! As such, we are really excited to announce the second Alloy update for May. Here are some of the highlights of this release.

Trigger Workflow from Items

We have had the ability to create manually triggered workflows for a few months now, this feature extends that feature by providing the option to trigger those workflows from an item.

This would allow you to create custom complex actions for particular designs and for people to carry them out easily through a single selection.

When setting up these Workflows, you may only want some users to be able to trigger them, you can control this by setting Read permissions for those users. Any user who does not have Read permissions will not be able to trigger it.

We've been looking forward to this feature and are really excited to see what creative uses for this everyone produces. For uses such as completing all jobs on an item, creating an invoice or emailing a supervisor, the possibilities are endless.

Workflow Emails - Multiple Recipients

Previously, whenever you wanted your Workflow to send emails to multiple email addresses, you would need to create a separate node for each recipient. This update will now allow for multiple recipients to be listed under the Email To field. 

Just keep in mind that each recipient address will need to be delimited using a comma (,). When a Workflow is triggered with this set up correctly, an identical email will be sent to each of the addresses listed.

AQS Builder Relative Dates

Workflows have been able to define relative Dates and Times for a long time, but this useful piece of functionality has, until now, been missing from the AQS builder.

You can now use a relative date time as a comparator to other compatible attributes or values. This is particularly useful when you are defining saved queries as you no longer need to update any date values that are filtering your data to a specific time period. For example, you can create a saved query to display all Jobs raised within the last two weeks. 

The point in time from which the relative date time is taken from can also be configured to the following options:

• Now
• Start of Today
• End of Today
• Last Monday
• Start of the Week
• Start of the Month

Custom Reports on Items

An improvement has been made to the Reports pane. Due to a slight difference in how Standard and Custom Reports are linked to items, the Reports pane used to only show Standard Reports. This has now been changed to include any Custom Reports that have been linked.

To ensure that reports are linked to the Item they report on, when creating an Item Data Source in the Report Builder, be sure to check the option to Link report to item?

Task Assignment Current Date

We have been hearing some great feedback recently about the Task Assignment view, we also have a lot of great suggestions on how to make it a bit more user friendly. One of those changes present in this update is a small marker highlighting the current date, hopefully making it a bit easier to orientate where you are on the planner. 

 Alloy Community

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.