Templates

In this section:

You can use templates to define reusable information, such as contact information, alert templates and logger configuration. Using templates will save you a lot of work when creating shipments.

Contact templates

The Contact template is a list of contacts to notify if excursions occur during a shipment. The list can be simple or a matrix with a separate roles for each contact. It also defines their medium of communication.

The Contact template is important especially when the MARS service (Monitor and Respond Service) handles the shipment monitoring for the customer to ensure all alerts go to the right contact.

Alert templates

The Alert template is used to define the conditions for raising an alert. The Alert template is used to assign upper and lower-bound alert values to shipments and loggers. More than one Alert template can be tied to each shipment, raising alerts with different criteria.

Logger templates

A Logger template defines reusable configuration for one or more loggers assigned to a shipment. Different logger templates are usually created for different types of transport and different duration of trips. Each aims at best practices for different transport methods, length of the journey as well as variations in handling the shipments.

Deleting templates

You can delete templates you no longer need.

Create contact template

Contact templates define a reusable set of contact information (SMS and emails) that should receive direct excursion notifications.

When you create a shipment, you reference the unique reference to the contact template, and the information is made available to logger devices and used to send out alerts for the shipment.

Best practices

Only add relevant contacts:
- Reverse logistics contacts
- Alert/ Warning contacts

Create contact template

Creates a new contact template with the given reference value.

Endpoint: https://integrations.controlant.com/api/scm/shipments/create

Table 60. Create contact template

Item	Description
`reference`	Unique reference to contact template, created by the customer. You can use this to reference the contact template when you create a shipment.
`contacts`	List of contact details. You can define separate contacts for different severity alerts. For each contact you need to define the following:
	`contactType`	Type of contact information. Configures how to send the alert. Email - Send alert to email address SMS - Send alert by SMS to phone number.
	`contactAddress`	Contact address. Depending on configuration of `contactType`, either email address or phone number that can receive SMS messages.
	`deliveryEvent`	Type of event to send to contacts when shipments are delivered at destination. None - Do not send a delivery event to the contact Simple - Send a simple notification to the contact Reports - Send a complete delivery report to the contact
	`minimumSeverity`	Lowest severity level that this contact should be notified about. All severities higher than this value are automatically included. None - No alerts will be sent to the contact. Level0 - Alerts sent to the contact when loggers report a Notification (Severity 0 alert) or higher. This is the lowest severity level setting and effectively includes all alerts for the logger devices. Level1 - Alerts sent to the contact when loggers report a Severity 1 alert or higher. Level2 - Alerts sent to the contact when loggers report a Severity 2 alert or higher. Level3 - Alerts sent to the contact when loggers report a Severity 3 alert.

Example request

{
  "reference": "1234567890AB",
  "contacts": [
    {
      "contactType": "Email",
      "contactAddress": "joe-wants-it-all@example.com",
      "deliveryEvent": "None",
      "minimumSeverity": "Level0"
    },
    {
      "contactType": "Email",
      "contactAddress": "support@example.com",
      "deliveryEvent": "Reports",
      "minimumSeverity": "Level2"
    },
    {
      "contactType": "SMS",
      "contactAddress": "555-8888",
      "deliveryEvent": "None",
      "minimumSeverity": "Level3"
    }
  ]
}

Example response

{
  "templateReference": "1234567890AB",
  "success": true,
  "responseTime": 0
}

Create alert template

Alert templates define a logger boundary configuration template similar to the warning templates that can be created manually in the SCM web portal. Alert templates differ from warning templates in that shipments can have more than one alert template which can be merged to form a new warning template with special properties such as calculating the narrowest safest alerting configuration for a mixed product shipment.

The alert template should be used to specify default values to assign to loggers when they are added to shipments.

Best practices

Add something?

Create contact template

Creates a new alert template with the given reference values. This template should be used to assign upper and lower bound alert values to shipments and loggers.

Endpoint: https://integrations.controlant.com/api/scm/templates/contact/create

Table 61. Create alert template

Item	Description
`reference`	Unique reference to alert template, created by the customer. You can use this to reference the alert template when you create an alert.
`alerts`	List of alert boundaries and configurations. Note You can configure multiple alerts in each alert template, e.g.: Level 3 alert - upper bounds Level 3 alert - lower bounds Level 2 alert - upper bounds Level 2 alert - lower bounds Level 1 alert - upper bounds Level 1 alert - lower bounds NoExcursion alert - upper bounds NoExcursion alert - lower bounds For each alert you need to define the following:
	`bounds`	Configures whether this alert is for upper bounds or lower bounds. `UpperBounds` - Alert will trigger on values exceeding the threshold `LowerBounds` - Alert will trigger on values falling below the threshold
	`dataType`	Type of sensor data to alert on. Currently only accepts `Temperature`. `Temperature` - temperature of the logger in Celsius
	`thresholdValue`	Value determining the alert threshold. An alert is triggered if measurement value goes above/below this value for longer than the time specified in accumulativeTimeLimit. Note Value is specified in each `dataType`'s minor units. E.g. for `Temperature` data, it should be scaled up by 10 as only a single decimal value is supported for temperature. E.g. value `375` translates to `37.5°C`, and value `-253` translates to `-25.3°C`. The range allowed for temperature is: Minimum `-273.1°C` Maximum `300°C` Example values: `375` - Trigger alert if temperature goes above/below `37.5°C` for longer than the time specified in `accumulativeTimeLimit`. `-253` - Trigger alert if temperature goes above/below `-25.3°C` for longer than the time specified in `accumulativeTimeLimit`. `-3` - Trigger alert if temperature goes above/below `-0.3°C` for longer than the time specified in `accumulativeTimeLimit`.
	`severity`	Severity of the alert that will be triggered if the measurement value goes above/below `thresholdValue` value for longer than the time specified in `accumulativeTimeLimit`. `NoExcursion` - No excursion registered when alert is triggered.. `Level1` - Alert will raise a Low (Level 1) excursion critically when triggered. `Level2` - Alert will raise a Medium (Level 2) excursion critically when triggered. `Level3` - Alert will raise a High (Level 3) excursion critically when triggered.
	`accumulativeTimeLimit`	Time limit this alert condition is allowed to be violated until it is triggered, in seconds. If the measurement value goes above/below `thresholdValue` value for longer than the time specified here, it will trigger an alert. Example value: `600` - Alert will be triggered if measurement value goes above/below `thresholdValue`value for more than 10 minutes. `300` - Alert will be triggered if measurement value goes above/below `thresholdValue`value for more than 5 minutes.

Example request

{
  "reference": "Actemura-400mg-Tablets-AlertTemplate",
  "alerts": [
    {
      "bounds": "UpperBounds",
      "thresholdValue": 30,
      "dataType": "Temperature",
      "accumulativeTimeLimit": 60,
      "severity": "Level3"
    },
    {
      "bounds": "LowerBounds",
      "thresholdValue": -1,
      "dataType": "Temperature",
      "accumulativeTimeLimit": 10,
      "severity": "Level3"
    },
    {
      "bounds": "UpperBounds",
      "thresholdValue": 15,
      "dataType": "Temperature",
      "accumulativeTimeLimit": 20,
      "severity": "Level2"
    },
    {
      "bounds": "LowerBounds",
      "thresholdValue": 5,
      "dataType": "Temperature",
      "accumulativeTimeLimit": 15,
      "severity": "Level2"
    }
  ]
}

Example response

{
"templateReference": "1234567890AB",
"success": true,
"responseTime": 0
}

Create logger template

Logger templates define reusable configuration characteristics for one or more loggers assigned to a shipment.

Note

Typically, different logger templates are created for different transport modes (e.g., ocean, air, road) and duration of transport that serves the purpose of saving battery power on long ocean voyages for example. Other uses include flexibility in dealing with different handling processes at either receiving or shipping sites or differences in delivery or shipping conditions.

Best practices

Add something?

Create logger template

Creates a new logger template with the given reference values. Use this template to specify default values to assign to loggers when added to shipments.

Endpoint: https://integrations.controlant.com/api/scm/templates/logger/create

Table 62. Create logger template

Item	Description
`reference`	Unique reference to logger template, created by the customer. You can use this to reference the logger template when you create an alert.
`shippingMethod`	Method to use to determine the shipment logger is assigned to has been shipped. GeoFence - Shipping triggered by the logger leaving a predefined GeoFence area. Button - Shipping initiated by pressing the Start button on the device. GeoFenceOrButton - Shipping initiated by pressing the Start button on the device OR the logger leaving a predefined GeoFence area.
`deliveryMethod`	Method to use to determine the shipment logger is assigned to has arrived at destination and can be considered delivered. GeoFence - Delivery triggered by the logger entering a predefined GeoFence area. Button - Shipping initiated by pressing the Stop button on the device. GeoFenceOrButton - Delivery initiated by one of the following: Pressing the Stop button on the device. Logger entering a predefined GeoFence area. GeoFenceAndButton - Delivery initiated by both of the following: Pressing the Stop button on the device. Logger entering a predefined GeoFence area.
`warningsIgnorePeriodAtStart`	Period at the beginning of shipment where the alarm functionality is inactive, in seconds. Note During ignore periods temperature data is recorded and will be available, but excursions will not trigger an alert. Example: If product is placed in a truck or package for transport that is not preconditioned, you can set `WarningsIgnorePeriodAtStart` to 2 minutes to allow for temperature to settle without raising alarms.
`warningsIgnorePeriodAtEnd`	Period at the end of shipment where the alarm functionality is inactive, in seconds. Note During ignore periods temperature data is recorded and will be available, but excursions will not trigger an alert. Example: If there is a known delay at destination from the time logger is removed from product and until the stop button is pressed on all loggers, you can set `WarningsIgnorePeriodAtEnd` to 5 minutes to allow for button press delays while arranging product at receiving end.
`excursionSeverityThreshold`	Threshold before alerts are raised for this shipment. `NoExcursion` - No excursion registered when alert is triggered.. `Level1` - Alert will raise a Low (Level 1) excursion critically when triggered. `Level2` - Alert will raise a Medium (Level 2) excursion critically when triggered. `Level3` - Alert will raise a High (Level 3) excursion critically when triggered.
`preferredWakeUpInterval`	Sets a preferred wake up interval to apply to loggers in this shipment. Default - Logger will wake up up every 1 hour. The default. TwoHours - Logger will wake up every 2 hours. ThreeHours - Logger will wake up every 3 hours. SixHours - Logger will wake up every 6 hours. TwelveHours - Logger will wake up every 12 hours. Note This is a very long sleeping period and should be reserved for special cases where battery-life is critical (e.g. logger in long duration storage in warehouse). TwentyFourHours - Logger will wake up every 24 hours.NOTE: This is an extremely long sleeping period and should be reserved for special cases where battery-life is critical (e.g. logger in long duration storage in warehouse). Note This is a very long sleeping period and should be reserved for special cases where battery-life is critical (e.g. logger in long duration storage in warehouse). Note This is only available/applicable to Saga loggers.

Example request

{
  "reference": "1234567890AB",
  "shippingMethod": "Button",
  "deliveryMethod": "GeoFenceAndButton",
  "warningsIgnorePeriodAtStart": 0,
  "warningsIgnorePeriodAtEnd": 0,
  "excursionSeverityThreshold": "Level3",
  "preferredWakeUpInterval": "Default"
}

Example response

{
  "templateReference": "1234567890AB",
  "success": true,
  "responseTime": 0
}

Delete template

You can delete templates you do not need anymore.

Delete template

Creates a new contact template with the given reference value.

Endpoint: https://integrations.controlant.com/api/scm/templates/delete

Table 63. Delete template

Item	Description
`reference`	Unique reference to template you want to delete. Reference is created by the customer.
`type`	Type of template to delete. Note Template type must match the template type of the template you want to delete, or you will receive an error response. Alert - Alert template Contact - Contact template Logger - Logger template

Examples

Example request

{
"reference": "DC1-LoggerTemplate",
"type": "Logger"
}

Example response

{
  "success": true,
  "responseTime": 200
}

Templates

Contact templates

Alert templates

Logger templates

Deleting templates

Create contact template

Best practices

Create contact template

Example request

Example response

Create alert template

Best practices

Create contact template

Note

Note

Example request

Example response

Create logger template

Note

Best practices

Create logger template

Note

Note

Note

Note

Note

Example request

Example response

Delete template

Delete template

Note

Examples

Example request

Example response

Search results