Filter results by

The Manifest

ARTIK Cloud is designed to communicate with any device regardless of how data is structured. Devices can upload data to ARTIK Cloud in any format that works for them, and can send data to targeted devices via ARTIK Cloud in any format that works for the targeted devices. Data is contained in a message.

ARTIK Cloud uses what we call the Manifest to interpret the content so that it can be stored properly, or be sent to targeted devices correctly. When defining or updating a device type, you must provide a Manifest that describes the device data. Once you define the Manifest for your device type, ARTIK Cloud can then make its data available to other services and devices.

The Developer Dashboard offers two ways to create a Manifest. The Simple Manifest is ideal for standard data that does not need any processing. It can quickly be created via a Web form with a drag-and-drop interface, and no scripting or coding is involved. This Web form determines the structure of the JSON payload sent by your devices. Simple Manifests are automatically approved. See this blog post for step-by-step instructions on creating a Simple Manifest.

The Simple Manifest is the quickest path to production and the best option for fast prototyping. It gives you the flexibility of structuring messages in JSON and a Web interface that requires no code, but less freedom to create sophisticated data formats.

The Advanced Manifest is what we cover on this page. This is a script written in Groovy to process messages as they come in one-by-one. Messages are structured to contain a single package of data (no batch uploads) that goes through the Manifest. This keeps data organization and processing straightforward. All Manifests written in Groovy must be approved by our team before they can be used.

The Advanced Manifest is your best option if you already have devices deployed, or you have an existing application and want to integrate ARTIK Cloud. It requires more work and must be certified, but gives you the power to create highly sophisticated data formats.

Peek into the basics

Write a basic Manifest

Manifests are created using the Manifest SDK. Your Manifest is a derived class of the Manifest base class. In that class, you must define a list of fields that composes your data and complete two methods: normalize and getFieldDescriptors.

  • normalize requires most of your attention. You must take the data as it is generated by a device or service, and split it into values for the fields you defined.

  • getFieldDescriptors only requires that you return a list of the fields in your data. This will be useful when a client wants to inspect the device and understand what data is available.

Manifest template

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import com.samsung.sami.manifest.Manifest
import com.samsung.sami.manifest.fields.*

public class TestGroovyManifest1 implements Manifest {

  // Custom FieldDesc
  // Create your field descriptors here

  // Implement the normalize method, parse your data as it comes in and spit out a list of fields with normalized values
  @Override
  List<Field> normalize(String input) {
  
    // return a list of Fields here    
    return []
  }

  // implement the getFieldDescriptors method, return the list of fields that your data will contain so that others know
  List<FieldDescriptor> getFieldDescriptors() {
    // return a list of FieldDescriptors here
    return []
  }
}

Below is an example of a Manifest with the basic information filled in.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import groovy.json.JsonSlurper

import com.samsung.sami.manifest.Manifest
import com.samsung.sami.manifest.fields.*

public class BasicManifest implements Manifest {

  // Custom FieldDesc
  // The device sends a single data point and it's a String that describes its status
  static final STATUS = new FieldDescriptor("status", String.class)

  @Override
  List<Field> normalize(String input) {
    // data is sent by the remote device as a JSON, so ARTIK Cloud will need to use a library to understand it
    def slurper = new JsonSlurper()
    // If the device sent the data in a more complex format here developer can implement their String operations, loops, etc. In our case it's a single field, very easy.
    def json = slurper.parseText(input)

    // now we return the Field to the system
    return [
      new Field(STATUS, (String)json.status)
    ]
  }

  @Override
  List<FieldDescriptor> getFieldDescriptors() {
    // This is a single field, if it was more than one it would be an Array
    return [STATUS]
  }
}

The data that can be correctly processed by the above Manifest looks like:

1
2
3
{
  "status": "on"
}

We have created a sample device type "Manifest SDK Sample Device". If you just want to try the ARTIK Cloud APIs, you can use this sample device type instead of creating your own. Its Manifest TestJsonUtilGroovyManifest is discussed in Advanced Manifest examples.

See Connecting a device to learn how to connect a device with this device type to ARTIK Cloud.

Manifests that support Actions

An application/device working with ARTIK Cloud can send an Action (command) to a specific device. For example: A mobile app sends a "Turn On" command to a smart light connected to ARTIK Cloud. The light turns on by acting on the command from ARTIK Cloud. A destination device (here, the smart light) must be connected to ARTIK Cloud via WebSockets in order to receive Actions.

Read our blog for a step-by-step example of using Actions with a smart light.

In order for your device type to support Actions, you must provide a Manifest that defines Actions. In addition, it is also your responsibility to implement the functionality for a device to act on the actions defined in the device type's Manifest.

Now enhance the above Manifest to support Actions. Your Manifest is derived from the Manifest and Actionable interfaces. In that class, you must define a list of Actions that your device can act on, as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
import groovy.json.JsonSlurper

import com.samsung.sami.manifest.Manifest
import com.samsung.sami.manifest.fields.*
import com.samsung.sami.manifest.actions.Action
import com.samsung.sami.manifest.actions.Actionable

public class ManifestWithAction implements Manifest, Actionable {

  // Custom FieldDesc
  // The device sends a single data point and it's a String that describes its status
  static final STATUS = new FieldDescriptor("status", "light on or off", String.class)

  @Override
  List<Field> normalize(String input) {
    // data is sent by the remote device as a JSON, so ARTIK Cloud will need to use a library to understand it
    def slurper = new JsonSlurper()
    // If the device sent the data in a more complex format here developer can implement their String operations, loops, etc. In our case it's a single field, very easy.
    def json = slurper.parseText(input)

    // now we return the Field to the system
    return [
      new Field(STATUS, (String)json.status)
    ]
  }

  @Override
  List<FieldDescriptor> getFieldDescriptors() {
    // This is a single field, if it was more than one it would be an Array
    return [STATUS]
  }

  @Override
  List<Action> getActions() {
    return [
      new Action("setOn", "Sets the light state to On"),
      new Action("setOff", "Sets the light state to Off"),
    ]
  }

}

The method getActions defines what Actions that device type can take. In this specific example, the device defined by ManifestWithAction acts on the Action it receives from ARTIK Cloud, then sets status to the correct state in a message, and finally sends the messages back to ARTIK Cloud. Again, it is your resonsibility to implement the correct logic on the device side.

Below is an example of the message payload that contains the Actions and can be correctly processed by the above Manifest. Also see Posting a message with Actions.

1
2
3
4
5
6
7
8
{
  "actions": [
    {
        "name": "setOn",
        "parameters": {}
    }
  ]
}

Applications and devices query ARTIK Cloud to get the Manifest of targeted devices, and then learn the supported Actions by parsing the Manifest properties.

Manifest certification

This section applies to Advanced Manifests only. The Simple Manifest is automatically approved!

Manifests are submitted when creating new device types in the Developer Dashboard. The ARTIK Cloud team reviews your submitted Manifests. You should receive a response within 1 business day of submitting your Manifest. If the response is taking longer than expected, please use the Feedback link on the left to send us a message.

On approval or rejection, you will receive an email with any necessary feedback on resubmitting your Manifest. Manifests are tested not only for consistency, but also for compliance to ARTIK Cloud standards of data categorization and performance.

In general, your Manifest code should be clean and efficient. Because you may eventually want to publish your device type for other developers to use, please write your Manifest bearing in mind that it may become a tool for the public.

Some typical reasons a Manifest can be rejected:

  • Not processing or returning data, due to being incomplete.
  • Having a name that is too generic to be published, or uses the names "Samsung" or "ARTIK Cloud."
  • Including println or log.
  • Attempting anything malicious.
  • Attempting to use local resources (files) or remote resources (network calls).
  • Consuming too much memory or generating memory leaks (unreleased references).

We also strongly encourage you to test the Manifest before submitting it. You may use the Manifest SDK as a command-line tool to validate your Manifest or use its testing APIs to write Manifest tests.

What to do

The following is a list of best practices to keep in mind when writing your Manifest. Please check your Manifest against this list before you submit. This will eliminate time needed to make basic corrections and focus the ARTIK Cloud team on helping you resolve more complex issues (if any) with your Manifest.

printout

Avoid including standard output such as println or logs in your Manifest.

Field descriptors

FieldDescriptor names should follow the convention of Java variable names. Avoid using the $ character in the name. For example, use new FieldDescriptor("activeSteps") rather than new FieldDescriptor("active_steps").

Standard fields, or aliases of standard fields, should be reused whenever possible. For example, use StandardFields.TEMPERATURE, or define the following to use a type different from the standard double type:

1
public final static FieldDescriptor TEMP_INTEGER = TEMPERATURE.alias(Integer.class)

The FieldDescriptor must also be created so that it may be returned by the getFieldDescriptors() method rather than the normalize() method. This is because not all the data returned by normalize() can be described.

For example, you would implement the following:

1
2
3
4
5
6
7
public final static FieldDescriptor TEMP_INTEGER = TEMPERATURE.alias(Integer.class)
normalize(){
return [ new Field(TEMP_INTEGER, value)]
}
getFieldDescritors(){
return [TEMP_INTEGER]
}

Instead of:

1
2
3
4
5
6
normalize(){
return [ new Field(new FieldDescriptor("temp1", ...), value)]
}
getFieldDescritors(){
return [???]
}

Units

Units should be specified wherever appropriate. For example, specify units with distance or weight count, but not with step count, which is a quantity.

Standard units, defined in the JScience(SI or NonSI) package or in the StandardUnits class, should be reused whenever possible.

Conversions

The Manifest library can perform unit conversions for you. Rather than write a conversion from input unit to expected output unit, when creating an instance of a Field you can usually pass the unit that the value is expressed into. For example:

1
new Field(MIN_TEMPERATURE,NonSI.FAHRENHEIT, Double.parseDouble((String)json.minTemp)))

Utilities

To make your life easier, we recommend that you use the JSON utility classes, such as the Groovy utilities, when parsing JSON or other string-based input.

normalize() method

nomalize() must capture some data or fail, rather than send an empty result.

About the Manifest SDK

Writing a Manifest for ARTIK Cloud and testing it should be a straightforward process. You use the Manifest SDK to achieve that. The Manifest SDK offers two major functionalities:

To learn how to write and perform Manifest tests, see Validate your Manifest.

Groovy utilities

The Groovy utilities packaged with the Manifest SDK contain a few APIs meant to be used in a Manifest. Advanced Manifest examples illustrates that these APIs make writing your Manifest very easy.

Groovy utilities are not documented in the Manifest SDK API reference.

JsonUtil

This is a small set of utility methods helpful to manipulate JSON in a Manifest. JsonUtil currently exposes the function addToList, which is overloaded with different parameter combinations.

addToList extracts a field with the same name as the FieldDescriptor name from the JSON object and adds it to a list of fields. The call is safe if the property does not exist in the JSON object.

Parameter Description
fields a groovy list of fields
json a JSON object returned by a JsonSlurper parse method
fd an ARTIK Cloud field descriptor

addToList extracts a field with the same name as the FieldDescriptor name from the JSON object and adds it to a list of fields using a unit other than the one specified in the field descriptor to interpret the input value. The call is safe if the property does not exist in the JSON object.

Parameter Description
fields a groovy list of fields
json a JSON object returned by a JsonSlurper parse method
unitForInputValue the unit to use to interpret for the input value
fd an ARTIK Cloud field descriptor

addToList extracts a field with the name propertyInJson from the JSON object and adds it to a list of fields with the FieldDescriptor name. The call is safe if the property does not exist in the JSON object.

Parameter Description
fields a groovy list of fields
json a JSON object returned by a JsonSlurper parse method
propertyInJson the name of the property in the JSON object
fd an ARTIK Cloud field descriptor

addToList extracts a field with the name propertyInJson from the JSON object and adds it to a list of fields using a unit other than the one specified in FieldDescriptor to interpret the input value. The call is safe if the property does not exist in the JSON object.

Parameter Description
fields a groovy list of fields
json a JSON object returned by a JsonSlurper parse method
propertyInJson the name of the property in the JSON object
unitForInputValue the unit to use to interpret for the input value
fd an ARTIK Cloud field descriptor

StringFieldUtil

These utility methods are useful for writing Manifests when reading field values as strings or text (XML, CSV, etc).

These only work for the basic supported types (Boolean, Double, Float, Integer, Long, String) and not for collections (e.g., "string1, string2, string3" will not be interpreted as a collection but as a string).

addToList adds a field with the given FieldDescriptor and the text value using the value class defined in the descriptor and adds it to the specified list of fields. The call does not add the value if the value is null or empty.

Parameter Description
fields a groovy list of fields
value a text value for the field to add
fd an ARTIK Cloud field descriptor

addToList adds a field with the given FieldDescriptor and the text value using the value class defined in the descriptor and adds it to the specified list of fields using a unit other than the one specified in the field descriptor to interpret the input value. The call does not add the value if the value is null or empty.

Parameter Description
fields a groovy list of fields
value a text value for the field to add
unitForInputValue the unit to use to interpret for the input value
fd an ARTIK Cloud field descriptor