Filter results by

Using Cloud Connectors

We recently introduced new features for Cloud Connectors. See below!

ARTIK Cloud can accept data from any device, but some devices already send data to a third-party cloud. In this case, ARTIK Cloud can connect to the third-party cloud and use it as the data source for a device type. We have built an infrastructure called Cloud Connectors that enables you to connect the third-party cloud to ARTIK Cloud. ARTIK Cloud can then retrieve the device's data sent to that cloud.

A Cloud Connector brings a third-party device into the ARTIK Cloud ecosystem. Once there, it can communicate with other devices through features like ARTIK Cloud Rules, which uses ARTIK Cloud messages to trigger device commands. ARTIK Cloud enables cloud-connected devices to benefit from data aggregation and analytics across silos.

This article gives a high-level overview on how to build a Cloud Connector. Implement a Cloud Connector explains how to use the Cloud Connector SDK to write Connector Code. After reading both articles, you should read our tutorial Your First Cloud Connector to see an example.

Cloud Connectors

Eligibility

You can build a Cloud Connector for the third-party cloud if it:

  • Uses OAuth 1 or OAuth 2 for authentication.
  • Provides subscribe/notification APIs for ARTIK Cloud to subscribe and receive notifications about new data.
  • Has public APIs to read data from the cloud.

Building Cloud Connectors as a developer

There are two parts to building a Cloud Connector:

  1. Create and configure an ARTIK Cloud device type configured to receive data from a cloud service on ARTIK Cloud.
  2. Create and configure an "ARTIK Cloud Connector" application on the third-party cloud. This enables ARTIK Cloud devices of the above type to interact with that cloud.

For the second part, refer to the developer documentation of the third-party cloud to learn how to create an application. Our Cloud Connector tutorial also gives an example. The rest of this section will focus on the first part only.

Cloud Connectors

Configure a device type as a Cloud Connector

To connect a third-party cloud to ARTIK Cloud, we first need to define a device type. All data coming in from the third-party cloud will be associated with this device type. We do this by creating a new device type in the ARTIK Cloud Developer Dashboard.

Once you have entered the basic information, you will define a Manifest for your device type. In doing so, reference the documentation for the third-party cloud. See Create device type Manifest in our Cloud Connector tutorial to learn how third-party documentation formed the basis of our Manifest.

See ARTIK Cloud Basics for a refresher on how device types and Manifests work in ARTIK Cloud.

For a Cloud Connector, we take a different path than usual. We first tell ARTIK Cloud that the source is not a physical device but a cloud service. At the bottom of the Device Info tab, change the Device Data Source from "sends directly to ARTIK Cloud" to "sends data to a cloud that ARTIK Cloud will subscribe to". This will unfold two additional tabs for configuring the Cloud Connector:

ARTIK Cloud Cloud Connectors

Set authentication parameters

In the Cloud Authentication tab, you tell ARTIK Cloud how to authenticate itself to the third-party cloud. Select either "OAuth1" or "OAuth2", depending on which protocol is supported by the cloud. For clouds that do not require user authentication, use "None".

ARTIK Cloud Cloud Connectors ARTIK Cloud Cloud Connectors

The following tables describe the parameters displayed in the Developer Dashboard that correspond to each authentication protocol.

Some parameters are obtained from third-party documentation. Other parameters, such as Client ID and Client Secret, are provided only once you define an application on the third-party cloud. See our tutorial to create an ARTIK Cloud Connector application on the third-party cloud.

OAuth 1 parameters

Parameter name Description Default value
Request Token URL The request token URL provided by the third-party cloud.  
AccessTokenURL The access token URL provided by the third-party cloud.  
AuthorizationURL The authorization URL provided by the third-party cloud.  
Consumer Key The consumer ID provided by the third-party cloud.  
Consumer Secret The consumer secret provided by the third-party cloud.  
Signature Method The signature method to use in the Oauth 1 flow (HMAC-SHA1, RSA-SHA1, Plaintext) HMAC-SHA1
Transmission Method When making an OAuth-authenticated request, protocol parameters as well as any other parameter using the "oauth_" prefix SHALL be included in the request using one and only one of the following locations, listed in order of decreasing preference: HTTP Authorization header, HTTP request entity-body, HTTP request URI query HTTP Authorization header
Credentials Parameters A map to identify the fields "userid", "token", "secret", "external_id" in the request Identity

OAuth 2 parameters

Parameter name Description Default value
Authorization URL The authorization URL provided by the third-party cloud.  
Access Token URL The access token URL provided by the third-party cloud.  
Client ID The client ID provided by the third-party cloud.  
Client Secret The client secret provided by the third-party cloud.  
scope The OAuth 2 scope parameter provided by the the third-party cloud.  
Credentials Params A map to identify the following fields in the request: access_token, token_type, refresh_token, expires_in, external_id Identity

Two additional parameters, redirect URL and notification URL, are already populated and can be used to create an ARTIK Cloud Connector application on the third-party cloud. Depending on your scenario, you may not need a notification URL.

Configure the cloud subscription

The Connector Code tab is the final step of building a Cloud Connector. Here you can paste or upload Groovy code that tells ARTIK Cloud how to interact with the third-party APIs in order to get data from the cloud.

Cloud Connectors

You implement a Cloud Connector Groovy code using the Cloud Connector SDK. The SDK's GitHub repository contains libraries, API reference documentation, sample codes, and a template project. You can perform unit and integration testing using the SDK.

About the Cloud Connector Groovy code

The code implements a derived class of CloudConnector base class from the SDK. The following diagram illustrates the major steps and methods. All these steps are performed for individual devices of a Cloud Connector device type.

Cloud Connectors

As seen in the above image, a Cloud Connector uses subscribe/notification APIs to access data in three steps:

  1. subscribe: Subscribe to notification.
  2. notification: Receive notification.
  3. fetch: Call endpoint(s) to get data if needed.

The following methods are optional. Override a method only when it is necessary. See Implement a Cloud Connector for more information about these methods.

Method Description
signAndPrepare Called at the beginning of the methods initiated by ARTIK Cloud (subscribe, fetch and unsubscribe). It is a good practice to implement a generic process (i.e., add headers and signature) in this function.
subscribe Called by ARTIK Cloud when a user has completed the Authentication process for a device. This method creates URLs (zero or more) to call an endpoint of the third-party cloud to subscribe to notifications for this device.
onSubscribeResponse Called by ARTIK Cloud for each response from the third-party cloud to the requests created in subscribe. It processes the result of the subscription. You may add additional logics if needed.
onAction Callback method triggered when the third-party cloud sends an Action to ARTIK Cloud. The Action must be defined in the device type Manifest. If the Action contains data, send data to ARTIK Cloud. Otherwise, call fetch.
onNotification Callback method triggered when the third-party cloud sends a notification to ARTIK Cloud. This function extracts parameters within the notification. If the notification contains data, send data to ARTIK Cloud. Otherwise, call fetch.
fetch Called by ARTIK Cloud for each HTTP request returned by onNotification and onAction. This function allows you to customize the request using the selected device's parameters. The request will be used to fetch data on the third-party cloud.
onFetchResponse Called by ARTIK Cloud for each response from the third-party cloud to the requests created in fetch. This method gets the data from the response and pushes it to ARTIK Cloud.
unsubscribe Called by ARTIK Cloud when the user disconnects the device.
onUnsubscribeResponse Called by ARTIK Cloud for each response from the third-party cloud to the requests created in unsubscribe.

Our tutorial and SDK sample code give examples of how to implement the above methods for a few clouds.

About custom parameters

At the bottom of the Connector Code tab, there is a Custom Parameters table. You can store key-value pairs in this table and then access them in your Cloud Connector Groovy code.

In the Groovy code, you do not hardcode the values of the custom parameters. Read the values from the table instead.

Later on, if you decide to change the value of a parameter, you only need to change its value in the table instead of changing the Groovy code. That is the benefit of using custom parameters—your Groovy code becomes more flexible.

To access key-value pairs in the parameter table, use the object of com.samsung.sami.cloudconnector.api.Context trait in the Groovy code. Context has the following interface, per the Cloud Connector API doc:

1
2
3
4
5
6
7
8
9
10
11
trait Context extends scala.AnyRef {
    def cloudId: String
    def clientId: String
    def clientSecret: String
    def scope: JList[String]
    def parameters: JMap[String, String]
    def debug(obj: Object)
    /** epoch in millis */
    def now(): Long
    def requestDefTools: RequestDefTools
}

Let's use an example to explain how to access the parameters in the table. Add two key-value pairs in the Custom Parameters table as shown in the screenshot below:

ARTIK Cloud Connector Custom Parameter table

Under the hood, the ARTIK Cloud Developer Dashboard generates the following parameters JSON object based on the table.

1
2
3
4
5
6
7
8
{
  ...
    "parameters": {
      "myUrl": "http://www.foo.com/bar",
      "myNum": "10",
    },
  ...
}

You access these parameters via Context in your Cloud Connector Groovy code as follows:

1
2
3
4
5
6
7
@Override
Or<List<RequestDef>, Failure> subscribe(Context ctx, DeviceInfo info) {
    ...
    ctx.parameters()["myUrl"]...
    ctx.parameters()["myNum"]...
    ...
}

Not only can your Groovy code access all the parameters in the Custom Parameters table, but also some of the parameters in the Cloud Authentication tab. Based on the com.samsung.sami.cloudconnector.api.Context interface above, you can read the values of the three parameters of Cloud Authentication as follows:

1
2
3
4
5
6
7
8
@Override
Or<List<RequestDef>, Failure> subscribe(Context ctx, DeviceInfo info) {
    ...
    ctx.clientId...
    ctx.clientSecret
    ctx.scope...
    ...
}

Approval

Your Cloud Connector needs to be approved by the ARTIK Cloud team before you can use it. Because ARTIK Cloud executes your Groovy code, we will check that there is nothing harmful before uploading your code on the platform. You will receive an email on the status of your Groovy code within 24 hours of submitting it.

Recall that we have an approval process for Advanced Manifests submitted in the Developer Dashboard. These are two different approval processes.

Using Cloud Connectors as a user

Once a developer has created a Cloud Connector, any user can connect a device of this device type in My ARTIK Cloud. The device connection process is identical to the normal flow except that the user must authenticate once with the third-party cloud, by clicking the "AUTHORIZE" button seen below:

Moves authorization

The authorization process then starts:

Moves authorization

New Cloud Connector features

We are excited to announce new capabilities for Cloud Connectors!

This means that a Cloud Connector can now retrieve data from a cloud on-demand, rather than depending on a third-party cloud to send a notification (our previous Cloud Connector tutorial explains how this works). Cloud Connectors are also now compatible with all clouds that support an HTTP API.

Receive Actions

A Cloud Connector can call the third-party cloud to make a request to receive data or send Actions to the cloud.

After you define the Actions in the Manifest, you may implement a new onAction function in your Cloud Connector. In this function, you can define the request you want to send to the third-party cloud. As with notifications, the requests will be processed by the fetch function before being sent to the third-party cloud, and will be received in onFetchResponse. A message can be pushed directly to ARTIK Cloud using onActionData (as with onNotificationData for notifications).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
abstract class CloudConnector {
[...]
    /**
      * Callback_5: Called for each action received.
      * The request targets 1 device. Optionally build data request with info from the Device.
      * Fetch function will be called with the RequestDef included in.
      * Default impl:
      * {{{
      * Bad(Failure("unsupported: method onAction should be implemented"))
      * }}}
      */
    def onAction(ctx: Context, action: ActionDef, info: DeviceInfo): ActionResponse Or Failure = {
        Bad(Failure("unsupported : method onAction should be implemented"))
    }
  
    /**
     * Callback_6: Called for each pushed data generated by onAction
     */
    def onActionData(ctx: Context, info: DeviceInfo, data: String): JList[Event] Or Failure = {
        Bad(Failure("unsupported: method onActionData should be implemented"))
    } 
}

No authentication

It is now possible to access clouds that do not require user authentication. Select "None" in the authentication drop-down in the Developer Dashboard, or set authType to none in the Cloud Connector definition.

Polling

Ask ARTIK Cloud to send an Action to a third-party cloud on a defined period using the polling key in the Cloud Connector definition. Polling can be used to set one or more scheduled Actions.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
[...]
    // Setup polling
    // cron: a cron expression
    // action: the action that will be called
    "polling": [{
        "cron": "0 0 * * * *", // every hour
        "action" : {
            "name": "actionName",
            "parameters": {
                "param1": "paramvalue1",
                "param2": 2
            }
        }
    }]
}