Importing new or changed records from SpeedyCraft

When importing new or changed records from SpeedyCraft, there are some terms/properties that need some explanation:

• UpdateInfoExt
• RowVersion
• ExternalStatus

These three in combination would help external applications to write efficient integrations to SpeedyCraft.

UpdateInfoExt

UpdateInfoExt status field is used to express that the record is new or changed to external application. Please note that an external application should NEVER use "UpdateInfoExt > 0" as a filter for getting new and changed records. This would also give you incomplete/deleted records as well. 

A normal SpeedyCraft integration would use e.g. oAssignment.Open("UpdateInfoExt IN (1,2)", "") or oAssignment.Open("UpdateInfoExt IN (1,2) AND ExternalStatus IN (0,2)", "") to find Assignment-records to import (please use the correct syntax for the API version you're targeting). 

When the external application has imported the record, it should reset the UpdateInfoExt to 0, as this notes that the external application has already imported the record. If SpeedyCraft later changes this record, it will get UpdateInfoExt 1, and the external application may reimport it with the latest changes.

UpdateInfoExt should only be reset (e.g. set to 0) by the integration for the main application. In other words, if several applications integrate to SpeedyCraft for the same client, only the master application should control this. 

Also note that all changes to a record will update RowVersion. This means that if you set UpdateInfoExt = 0, this will trigger an updated RowVersion value for this record, and if you import records based on RowVersion only, this would trigger another import. 

RowVersion

Entities that might change in SpeedyCraft also have a RowVersion property. This is a value controlled entirely by the Microsoft SQL Server database, and behaviour is described in this article. 

So for each insert or update to the row, the rowversion gets a higher value than all other rowversions in the entire database (client/customer specific!). 

This property makes it possible to ask for new/changed rows within a specific entity. If you ask for neworchanged rows with rowversion > 0, you will get all rows in the SpeedyCraft table. Save the largest rowversion for that particular entity, and use this the next time. Then you will only get rows that have been changed since previous data fetch. 

Please note that if using RowVersion (neworchanged endpoints), you will also get the record as changed after you update the record with UpdateInfoExt=0 as mentioned above.

Using the GetFundamentals endpoint mentioned later gives a very effective way to get new data from SpeedyCraft. 

ExternalStatus

When importing a record from SpeedyCraft, you might have some rules that would block this record from beeing imported. By setting the ExternalStatus of this record to 1, you would note to SpeedyCraft that this is rejected by the external application, and allow the user to either change it or delete it. If then changed /deleted in SpeedyCraft, SpeedyCraft sets ExternalStatus to 2 to inform the integration that a response to the rejection has been processed.

If you want to inform the end-user about what was wrong, please add a Message through the Message endpoint to give him/her the details on this.

Webhooks

SpeedyCraft REST 2 API supports subscription for webhooks on several frequently used endpoints. 

Use GET Webhooks endpoint to get a list of available webhooks and POST Webhooks/subscription to register a webhook. 

GetFundamentals

SpeedyCraft REST 2 API offers a lightweight way to check several entities for changes in RowVersion / Max ID via the endpoint GetFundamentals. By using this endpoint, you will e.g. get the highest RowVersion entry for the entities you ask for. This information could then be used to compare with the highest RowVersion you already had synced on your side - and then only ask for changes on the entities where SpeedyCraft has a higher MaxRowVersion. So for a normal sync where no changes are present in SpeedyCraft, you would need only one request to the SpeedyCraft API, instead of the number equal to the entities you want to sync. 

Example of a working payload. Please skip maxId if you don't need it, and only use the entities you actually sync: 

{

    "fields": [

        "maxRowVersion",

        "maxId"

    ],

    "entities": [

        "Assignment",

        "AssignmentNote",

        "AssignmentParticipant",

        "AssignmentProduct",

        "AssignmentQualityControl",

        "AssignmentService",

        "Attachment",

        "Customer",

        "CustomerSite",

        "Schedule",

        "StorageTransfer"

    ]

}