SpeedyCraft entity Identity fields and object update details

Identity fields: Id, Idext, Idtext and UID

In the SpeedyCraft database, most tables/endpoints have several identity fields. This example from the Customer table describes how they are used.

When the external application integration adds new records, providing the Idext, then Idtext gets
the same value as default. Hence, if the external application just uses Idext, and has
no need to display a different ID, it does not have to set Idtext explicitly.

Adding data to SpeedyCraft

The Swagger documentation gives a complete set of properties for all objects. Please note that you don't have to send complete objects to the SpeedyCraft API, just send the values you care about via your integration. This gives SpeedyCraft the ability to provide default values to the rest - and these are more correct. If you e.g. set 0 or true on a property that you don't really integrate with your system, the API interprets this as you deliberately want to set this, thus clearing what was already on that record. 

In other words: Please omit properties in your JSON payload where you don't really care about the contents. SpeedyCraft will then use default values for new records and keep existing values in updates. 

The following paragraphs include special considerations for the various SpeedyCraft API variants mentioned in SpeedyCraft API documentation.

Special considerations when using SpeedyCraft REST API

When receiving objects via GET endpoints, you will get all properties from the SpeedyCraft API. But when you PUT or POST objects to SpeedyCraft, you should be aware of the following when it comes to working with id's:

When searching for existing records, the priority list in the API is 

1. Id (first priority)
2. Idext
3. UID

So if it finds a record in the mentioned Id-field, it will use this - and update all other fields on PUT. 

Example 1 using PUT on /api/Customer with payload

.. 
  "CustomerId": 10010,
  "CustomerIdext": "5008",
  "CustomerIdtext": "5008",
..

- this will search for a Customer with CustomerId = 10010 at our side, and update all other properties. Please note that the CustomerId property could be skipped in this payload as long as there is a hit in CustomerIdext or UID. 

Example 2 using PUT on /api/Customer with payload

.. 
  "CustomerId": 10010,
  "CustomerIdext": "",
  "CustomerIdtext": "65413",
..

- this will search for a Customer with CustomerId = 10010 at our side, and update all properties (except for CustomerId which is readonly). Please note that the CustomerIdext will now be reset to empty string regardless of what was the previous value. If you want to skip editing this property when setting new values via PUT, just omit it from the JSON payload, and it will be kept as before. 

Editing the Idext field - a word of warning

In the usecase where an ID in the external application is changed, you would like to do the same change in SpeedyCraft. This is possible, but some precautions must be taken.

When editing entity objects (e.g. Assignment, Customer etc) it is possible to send an entity object without the Id field in the payload. As an example, consider the following Assignment object:

{
    "AssignmentIdext": "PM1239",
    "AssignmentIdtext": "PM1239",
    "ParentAssignmentId": 0,
    "CustomerId": 56700,
    "Description": "An example Assignment object without AssignmentId"
    ...
}

In the above example, the AssignmentId field is omitted. If this Assignment object is used in a PUT transaction against the Assignment end point, there is a chance of overwriting an existing Assignment. If the use case is to edit the AssignmentIdext property of an existing assignment, one must make sure that the value of the AssignmentIdext does not already exist in the database. If there is another, different Assignment in the database with AssignmentIdext equal to "PM1239", this Assignment will be overwritten by the data given in the Assignment object above. This may not be intended. To avoid this, the safe bet is to include the AssignmentId in the Assignment JSON payload, as AssignmentId has the first priority:

{
    "AssignmentId": 12345,
    "AssignmentIdext": "PM1239",
    "AssignmentIdtext": "PM1239",
    "ParentAssignmentId": 0,
    "CustomerId": 56700,
    "Description": "An example Assignment object with AssignmentId"
    ...
}

The same rule applies to all entities, i.e. include the Id value of the entity (if possible) when editing entities.

Foreign keys  / clearing ID's

In e.g AssignmentQualityControl entities, we do have references to another table, QualityControl. The AssignmentQualityControl object then have both properties QualityControlId and QualityControlIdExt. Please note that these behave the same way. If you e.g GET an AssignmentQualityControl object with the following properties

.. 
  "QualityControlId": 115,
  "QualityControlIdext": null,
..

you will have to make sure that you don't accidentally clear this ID. If you PUT the object with an empty string in QualityControlIdExt, like this

.. 
  "QualityControlId": 115,
  "QualityControlIdext": "",
..

the API will get a hit on QualityControlId = 115, and nothing will change. The next GET result will be similar to the first. 

If you really want to clear the reference to QualityControl, you could do this by either set 

.. 
  "QualityControlId": 0,
..

or

.. 
  "QualityControlId": 0,
  "QualityControlIdext": "",
..

In the last example here, the QualityControlIdext is not used for anything. Foreign keys will have to be cleared by the Id field. 

So basicly, SpeedyCraft cleared the reference to the form template, as this is what was applied by the external application integration via SpeedyCraft API. 

Obsolete - Special considerations when using legacy SCImpExpNET

When filtering on the ID fields in the Open()-statement, there is one important aspect
to be aware of:
Any SpeedyCraft table that holds a foreign key, e.g. CustomerID in tblAssignment, will
only contain the internal SpeedyCraft ID field. Hence, one would conclude that only
CustomerID can be used in the WHERE-statement in Open(). However, the SCImpExp
object translates any references to IDExt automatically. This means that if you want to
list all Assignment registered on a customer with CustomerID=30000 and
CustomerIDExt=12000, you can use both these statements:

oCustomer.Open("CustomerID=30000","")
oCustomer.Open("CustomerIDExt='12000'","")

Notice that in the first example, there are no hyphens, since this is an integer. But
when using IDExt, hyphens must be added, as this is a string value.