Overview 

As part of our ongoing work to provide more detailed messaging from our API, we will be updating our responses to contain information regarding how close the caller is to reaching this limit in response headers.

Who will this affect?

This change will only affect users that are likely to exceed the API rate limit by providing them with greater feedback when this may occur. 

Details

As described in a previous post, our API will limit the number of calls that a user can make in line with our rate limiting policy.

We will be updating our responses to contain information regarding how close the API caller is to reaching this limit in response headers, for example:

X-Rate-Limit-Remaining: 99
X-Rate-Limit-Reset: 2021-03-16T11:08:08.0232125Z

This message informs you that if you make more than another 99 requests before the specified time, you will be subject to rate-limiting.  When the limit is exceeded, requests will then fail with HTTP 429, and there will be a response header letting you know how many seconds to wait until you will again be able to make requests, for example:

Retry-After: 15

Note that these are the standard headers recognised for HTTP rate limiting.

Expected Release Date

July 29th 2021

Overview

AQS expressions now support the ability to run queries with conditions on an item level count.

Who will be affected?

All existing users will be able to take advantage of this feature through the newly added AQS Count node.

Details

An item level count allows to have a condition on the number of items connected through a link attribute being equal, greater than, etc. to the value of another attribute on the same item.

Example Use Case

As an example, we can consider a query that wants to fetch the title and subtitle of all projects that are over capacity. That is all projects that have a number of tasks greater than or equal to their capacity, contained in attribute attributes_projectsCapacity_60464441c14e5d000ad7e47.

{
  "type": "Query",
  "properties": {
    "attributes": [
      "attributes_itemsTitle",
      "attributes_itemsSubtitle"
    ],
    "collectionCode": [
      "Live"
    ],
    "dodiCode": "designs_projects"
  },
  "children": [
    {
      "type": "GreaterThan",
      "properties": {
        "inclusive": true
      },
      "children": [
        {
          "type": "Count",
          "properties": {
            "groupBy": "attributes_projectsTasks"
          }
        },
        {
          "type": "Attribute",
          "properties": {
            "attributeCode": "attributes_projectsCapacity_60464441c14e5d000ad7e479"
          }
        }
      ]
    }
  ]
}

Prior to this change, users could only compare a count node against a static Number node.

Expected Release Date

June 24th 2021

Overview

We have added a new Interface designInterfaces_itemsMetadata to Alloy Core Blueprints. This interface has four attributes, which allow you to see the username of the user who created or last edited an item, as well as create/last edit date and time.

Who will be affected?

All existing customers will be upgraded to gain access to this new interface. As this interface is part of Alloy Core, all new customers will have access to this interface by default. 

Details

For users wishing to see metadata on your custom design items, the design will need to be updated to implement designInterfaces_itemsMetadata. 

Four new attributes added by this interface are:

• Created By: attributes_itemsMetadataCreatedBy the username of the user who created the item 
• Created Time: attributes_itemsMetadataCreatedTime the item created date and time 
• Last Edit By: attributes_itemsMetadataLastEditBy the username of the user who edited this item last 
• Last Edit Time: attributes_itemsMetadataLastEditTime the item last edit date and time 

All of the above attributes are computed automatically by the Alloy Engine on item creation and each item edit. They will then be available to view listed alongside other existing item attributes on the design. 

Use Case

Once this interface is added to a design, the new attributes could be used within the templates for title/subtitle as usual. For example, if users want to quickly see who created a job they are working on, they could edit their job design title to something like

JOB-{{attributes_jobsJobNumber}}:{{attributes_itemsMetadataCreatedBy}}

This would then appear on each item title as JOB-123:johnsmith where johnsmith is the username of the user who created that job.

Expected Release Date

June 24th 2021 

Overview

In order to improve the accessibility of Alloy Meshes, we will be adding support for Open API JSON and endpoint documentation. Following a detailed review of the exposed endpoints and data models, we will also be acting to implement the following deprecations to provide better consistency between naming and conventions with the Alloy Core, Extended and Forge API's. Finally, we will be making changes to the way in which the security token is passed to the Meshes to improve security. 

Security token to be removed from query string

We will no longer be accepting the token parameter which represents an Alloy API token on the query string, this should be passed via the HTTP headers in all future requests using the same key of token.

Example CURL before:

curl -X 'POST' \
  'http://localhost:3000/aws-iot/update-device?itemId=abc?token=123' \
  -H 'accept: application/json' \

Example CURL after:

curl -X 'POST' \
  'http://localhost:3000/aws-iot/update-device?itemId=abc' \
  -H 'accept: application/json' \
  -H 'token: 123' \

MeshResponseWithItemWebModel renames property itemResponse to item

The following meshes are expected to return a response which includes an item payload under the property itemResponse.

• alloy-push-mayrise-notice-mesh
• json-push-alloy-mesh
• telensa-fault-push-alloy-mesh

This property is being renamed to item but we will continue to return itemResponse until the date specified below for Phase 2. 

Example response before:

{
  "itemResponse": {
    "itemId": "af32ef...",
    ...
  }
}

Example response after:

{
  "itemResponse": {
    "itemId": "af32ef...",
    ...
  },
  // we will duplicate the data in the recommended item property
  "item": {
    "itemId": "af32ef...",
    ...
  },
}

Risk calculation mesh to remove itemsResponse property

The risk calculation mesh alloy-push-risk-calculation-mesh is removing the itemsResponse property as it was not correctly indicating the success of the response model, it isn't required and will therefore be removed as part of Phase 1 changes. 

When do these changes take effect?

The above changes will be rolled out in June 2021, with deprecations finally removed in January 2022 with the following expected release dates: 

Expected Release Date

Phase 1: June 24th 2021

Phase 2: February 24th 2022

Overview

As previously announced in Design Properties to Be Supported on Design Interfaces published on 03/08/2020, we are now implementing Phase 2 where obsolete properties are to be removed.

Please note that there will be a final Phase 3 to remove service code that exists to support backward compatibility, as described below.

Who will this affect?

This change will affect all integrations that have not been updated in line with the previously announced changes. Any integration relying on obsolete properties may cease to function.  

Details

Both Design and DesignInterface Web Models will no longer return title and subtitle string properties, rather just their DoDI equivalents dodiTitle and  dodiSubtitle with parent information. Similarly DesignWebModel will no longer return old properties named colour, icon, versioned, geometry and collections and their DoDI counterparts should be used instead.  

Following this change, the Design response will look as follows:

{
    "design": {
        "name": "Design Name",
        "code": "designs_designName_600aceb294eba00ddc382a9e",
        "context": "Customer",
        "implements": [{
                "code": "designInterfaces_items",
                "parent": "designs_designName_600aceb294eba00ddc382a9e"
            }, {
                "code": "designInterfaces_interfaceForImplements",
                "parent": "designs_designName_600aceb294eba00ddc382a9e"
            }
        ],
        "attributes": [...],
        "metadata": {...},
        "dodiTitle": {
            "value": "Design Title",
            "parent": "designs_designName_600aceb294eba00ddc382a9e"
        },
        "dodiSubtitle": {
            "value": "Interface Subtitle",
            "parent": "designInterfaces_interfaceForImplements"
        },
        "dodiColour": {
          "value": "#3d8fbd",
          "parent": "engine_defaultedProperties"
        },
        "dodiIcon": {
            "value": "icon-edited",
            "parent": "designs_designName_600aceb294eba00ddc382a9e"
        },
        "dodiVersioned": {
            "value": true,
            "parent": "designInterfaces_interfaceForImplements"
        },
        "geometryRequired": {
            "value": false,
            "parent": "engine_defaultedProperties"
        },
        "geometryAllows": {
            "values": [
                "Point",
                "LineString"
            ],
            "parent": "designs_designName_600aceb294eba00ddc382a9e"
        },
        "dodiCollections": {
            "values": [
                "Live",
                "Inventory",
                "Archive"
            ],
            "parent": "designs_designName_600aceb294eba00ddc382a9e"
        },
        "discriminator": "DesignWebModel"
    },
    "operationsSummary": {...}
}

DesignEditWebRequestModel 

Obsolete design geometry will be removed in favour of geometryRequired and geometryAllows properties introduced during Phase 1.

Phase 3 changes

At the moment service code does not apply changes to the design if it detects that value passed in is same as old value that comes from inheritance chain (implements or defaults). For the above design example this means if the edit is called with new subtitle being "Interface Subtitle" or colour "#3d8fbd", no parent change would be applied and returned designs will still come back with the same parents.

"dodiSubtitle": {
    "value": "Interface Subtitle",
    "parent": "designInterfaces_interfaceForImplements"
},
"dodiColour": {
  "value": "#3d8fbd",
  "parent": "engine_defaultedProperties"
}

However, after Phase 3 we will remove extra checks in the service and any property set on DesignEditWebRequestModel will use the edited design code as it's parent i.e. the above edit will result in parent change on retuned DoDI properties.

"dodiSubtitle": {
    "value": "Interface Subtitle",
    "parent": "designs_designName_600aceb294eba00ddc382a9e"
},
"dodiColour": {
  "value": "#3d8fbd",
  "parent": "designs_designName_600aceb294eba00ddc382a9e"
}

After Phase 3 is implemented, it will be caller's responsibility to check parent properties and not send properties that they do not want to set directly on the edited design i.e. if above parent change was not intended DesignEditWebRequestModel would be called with NULL subtitle and colour, which would ensure that returned value is calculated from the inheritance chain or defaulted.

Phase 2 Expected Release Date

March 25th 2021 

Phase 3 Expected Release Date

August 26th 2021

Overview

To improve security, we will be making changes to restrict the types of files that can be uploaded and downloaded via the API based on the extension.

Who will this affect?

This will affect anyone uploading files to or downloading files from Alloy that have extensions that could be deemed to be executables. 

Details

The Alloy API for file upload and download will restrict certain file extensions for security reasons. The list includes ".exe", ".bat", ".com" among others.

The list mirrors the extensions forbidden by Microsoft Outlook, see here for the full list of forbidden extensions.

Expected Release Date

February 25th 2021

Overview

As part of the work for the new Financial Accounts module, we are making changes to Extended Web API endpoints and logic to support Job Bill Items and Supplier/Customer Accounts.

Who is affected?

Users of Extended Web API who are using Work Item and Job Work Item endpoints.

This change is planned to roll out in two phases. This phase introduces new Extended Web API endpoints and marks old as obsolete, while the second phase will remove them.

Details

All Work Item and Job Work Item endpoints are now marked as obsolete i.e. routes starting with api/work-item or api/job-work-item. 

Job Work Units

For create, read, update and delete (CRUD) operations on Job Work Units (Job Work Items or Job Bill Items) callers should start using new Job Work Unit endpoints, starting with the api/job-work-unit route.

Work Items

The old Work Item endpoints are split into two routes: Work Unit api/work-unit and Change Component Work Item api/change-component-work-item. The first endpoint deals with applicable Design and Design Interfaces (DoDIs) for all Work Units (Work Items and Bill Items), while the second one handles applicable component DoDIs specifically for Change Component Work Items (i.e. items belonging to designs_changeComponentWorkItems).

Job Edit

As part of this change, the job edit endpoint now also handles Job Bill Items cost re-calculation when the parent asset item is set, changed, unset or the job status is changed to Completed. Please note that it is important to use the Extended Web API job edit endpoint api/job/{id} to alter the relationship between job and it's parent asset item, otherwise the cost calculation for Job Work Units will not be applied.

Budget Summary

The Budget summary endpoint api/budget/{id}/summary now returns extra results for each of BudgetPeriodJobCostsWebModel with information about the BillsPerJobStatuses in addition to existing CostsPerJobStatuses. Costs are calculated as before using costs of all Job Work Items for jobs that fall into specific budget period, while Bills now used the same logic but are using costs of Job Bill Items on jobs in budget periods.

Team Pricing to Account Pricing

As part of Finance Module, Team Pricing will become Account Pricing with all teams linked to an account sharing the pricing structure. Users should move any pricing data linked to a Team via attributes_teamsPricingTeamPricing to a supplier account (designs_supplierAccounts) using the attributes_financialAccountsPricing link instead as we plan on removing the link from Teams to Team pricing in due course.

The Extended API will first check for rates using Account Pricing  attributes_financialAccountsPricing but will continue to support cost calculation via attributes_teamsPricingTeamPricing when no account pricing is available for the time being. 

Additionally, all work items will now temporarily have two pricing attributes, the previous attributes_workItemsTeamPricing and a new link via work units pricing interface attributes_workUnitPricingPricing. Again, the Extended API code will first check for rates using the Work Unit pricing before falling back to the previous Work Item link. The Work Item link will also be removed once users have had opportunity to migrate their data. 

Expected Release Date

October 29th 2020

Overview

In an earlier announcement titled Removal of Item Title, Subtitle and Geometry properties (Phase 2), users were advised to update export AQS query to return the above attributes if they need them for their exported items. As part of these changes, we are making the ExportGeometry option obsolete as this can now be specified through the inclusion/omission of the geometry attribute in the query. 

Who will this affect?

Users querying the data with geometry via the API will be affected by the change.

Details

We are now making ExportGeometry optional and obsolete on the ExportWebRequestModel and it will be removed in due course in favour of requesting attributes_itemsGeometry as part of the export AQS attributes.

Expected Release Date

October 29th 2020

Overview

In order to better manage the levels of inbound requests to the API, we will be enabling Rate Limiting on all endpoints. This change is aimed at preventing all system users from being impacted by excessively high activity levels of a single user and Denial-of-Service (DoS) attacks.  

Who will be affected?

The defined rate limit will only affect API users making a considerably high number of calls for a sustained period. The rate has been set at a level that will not impact users using the API at reasonable activity levels or short bursts of high activity.

Details  

Sustained calls (monitored daily) of over 100 requests per minute on any endpoint will result in the corresponding API key being disabled. Where possible, we will notify API key owners before disabling, however we reserve the right to act without notice in order to maintain accessibility of the service for other users. 

We advise API users to review their usage prior to this change to avoid any service disruption.  

Any disabled key may be re-enabled via contacting the Support team and only once the cause of the high number of requests has been rectified. 

Expected Release Date

27th August 2020