# Track & Trace

:white\_check\_mark:Professional :white\_check\_mark:Premium :white\_check\_mark:Enterprise

{% hint style="info" %}
Swagger documentation for this connector is available on our playground environment. It is also possible to test the connector on this page, use the parameters below to try it out.
{% endhint %}

| Parameter       | Description                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------------- |
| URL             | <https://devdocs.ultimo.net/docs/index.html?version=v1&apiKey=7359c7be836f4a899b3f48b9e5240faf>      |
| ApiKey          | FC1555BA3F5C4C329155B5ADAC2E8AB0                                                                     |
| DynamicLocation | This can be a string value. Example: "Zone -  0001"                                                  |
| EquipmentId     | The Id of equipment. It is possible to use Equipment from every context (e.g., Medical Instruments). |
| ExternalId      | The external identification number of the entity Equipment. The API needs ExternalId or EquipmentId. |
| SpaceId         | This is the internal Ultimo Id of a room/space (entity).                                             |

## Functional details

The main goal of the connector is to receive and update information about the location of an asset. Other connectors can be used to create jobs or retrieve asset information. Three fields are added to the equipment table; Enable track and trace, Location and Last synchronisation date. The first one is a checkbox that indicates if the asset is being tracked. The connector will only update assets of which track and trace is enabled.

Ultimo is not suitable for *raw sensor data*, so it is not allowed to directly connect sensors to Ultimo or send unfiltered sensor data to Ultimo. The Track & Trace connector is intended to connect with a server or platform that collects and filters data from sensors. We expect the server or platform to only send relevant location data changes to Ultimo. In addition, the general limits and quotas of the Ultimo API must be respected.

#### Update location or space field in Ultimo <a href="#track-and-trace-id-updatelocationorspacefieldinultimo" id="track-and-trace-id-updatelocationorspacefieldinultimo"></a>

The external application can update the location in Ultimo. It's up to the external application when the synchronisation will take place and which field will be updated. The connector can be used by the external application. The REST API can also be used to update the space field.

#### Last synchronisation date <a href="#track-and-trace-id-lastsynchronisationdate" id="track-and-trace-id-lastsynchronisationdate"></a>

This field will be updated by Ultimo when the connector is used to update an asset.

#### Open Track & Trace application <a href="#track-and-trace-id-opentrack-and-traceapplication" id="track-and-trace-id-opentrack-and-traceapplication"></a>

It's possible to open the external application. The button 'Open external application' is available on the equipment screens. The URL can be set in the AET settings. In PerformanceFlow it can be used to point the location on a map.

## Technical details

### Basic URL (POST):

`https://customer.ultimo.com/api/V1/Action/REST_Equipment_UpdateTrackAndTraceLocation`

Header data:

| Parameter            | Description                                               |
| -------------------- | --------------------------------------------------------- |
| ApiKey               | Request an API key at (application manager or consultant) |
| ApplicationElementId | Fixed value: “32909ddd-068d-4a76-9f31-ba69bf7cf3ec”       |

### Body (example response)

```json
{
  "DynamicLocation": "Zone-00001",
  "EquipmentId": "00001",
  "SpaceId": "C-38"
}
```

{% hint style="success" %}
Status: 200 OK
{% endhint %}

```csharp
{
    "properties": {}
}
```

### Response when the action is not allowed:

{% hint style="danger" %}
Status: 400 Bad Request
{% endhint %}

```javascript
{
    "message": "The import of data cannot be executed. \r\nCause: Equipment record with Id '00001' cannot be found.",
    "type": 3,
    "code": "3524"
}
```

```javascript
{   "message": "The import of data cannot be executed. \r\nCause: Space record with Id '00001' cannot be found.",
    "type": 3,
    "code": "3524"
}
```

### Response when the API-key is missing:

{% hint style="danger" %}
Status: 401 Unauthorized
{% endhint %}

```csharp
{
    "message": "Missing API key",
    "code": "MissingApiKey"
}
```

### Response when the API-key is invalid:

{% hint style="danger" %}
Status: 401 Unauthorized
{% endhint %}

```csharp
{
    "message": "The API key is invalid",
    "code": "InvalidApiKey"
}
```