Creating and updating a protocol plug-in

System administrators can import a new or updated protocol plug-in by using the IBM® Watson IoT Platform - Message Gateway REST API PUT method. System administrators can then create the protocol plug-in by using the IBM Watson IoT Platform - Message Gateway REST API POST method.

Before you begin

To run a protocol plug-in, you must deploy the plug-in in IBM Watson IoT Platform - Message Gateway. The plug-in must be archived in a .zip file. This .zip file must contain the JAR file (or files) that implement the plug-in for the target protocol. The .zip file must also contain a JSON descriptor file that describes the plug-in content. This descriptor file is required in the .zip archive that is used to deploy a protocol plug-in. For more information about developing a protocol plug-in, see Developing a protocol plug-in.

Procedure

  1. Import the plug-in .zip file to IBM Watson IoT Platform - Message Gateway by using the IBM Watson IoT Platform - Message Gateway REST API PUT method with the following IBM Watson IoT Platform - Message Gateway file URI:

    http://<admin-endpoint-IP:Port>/ima/v1/file/<filename>

  2. To create or update an imported protocol plug-in, use the IBM Watson IoT Platform - Message Gateway REST API POST method.
    1. Use the following IBM Watson IoT Platform - Message Gateway configuration URI:

      http://<admin-endpoint-IP:Port>/ima/v1/configuration/

    2. Provide ProtocolPlugin object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json. Ensure that capitalization and double quotation marks are used as shown. 
      
{    
  "Plugin": {
    "<NameOfPlugin>": {
      "File": "string",
      "PropertiesFile": "string",
      "Overwrite": true|false
      }
   }
}
      Where:
      NameOfPlugin
      Required.
      Specifies a name for the plug-in.
      The name must match the value of the Name parameter in the plug-in configuration file. For information about the plug-in configuration file, see Developing a protocol plug-in.
      The maximum length of the name is 256 characters.
      File
      Specifies the name of the plug-in .zip file that you uploaded by using the IBM Watson IoT Platform - Message Gateway REST API PUT method.
      The maximum length of the plug-in .zip file name is 255 characters.
      PropertiesFile
      Optional.
      Specifies the protocol plug-in properties file name that you want to associate with the plug-in. You can develop a properties file in JSON format and the properties that it contains override any properties in the plug-in configuration file.
      The maximum length of the protocol plug-in properties file name is 255 characters.
      Overwrite: true|false
      Specifies whether an existing plug-in is overwritten if it has the same name.
      The default value is false which means that an existing plug-in is not overwritten if it has the same name.
  3. Stop and restart the IBM Watson IoT Platform - Message Gateway protocol plug-in server process. Use the IBM Watson IoT Platform - Message Gateway REST API POST method with the following URI: 
    http://<admin-endpoint-IP:Port>/ima/v1/service/restart

    Provide object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json: 

    
{    
  "Service": "Plugin"
}

    The installation of the plug-in takes effect only when the IBM Watson IoT Platform - Message Gateway plug-in server process is restarted. The plug-in can be updated at any time. You must specify "Overwrite":true to update an existing plug-in. The update is not effective until the plug-in server is restarted.

    The Enabled status of the protocol plug-in server process is set to true when you restart the plug-in server process after you install a protocol plug-in.

    You can check that the configuration of your protocol plug-in is as expected by using the IBM Watson IoT Platform - Message Gateway REST Administration API GET method. For more information about the GET method, see Viewing configuration details of objects that can be named by using REST Administration APIs.

Example

The following example shows the PUT method to import a plug-in zip file jsonmsg.zip by using cURL:
curl -X PUT -T jsonmsg.zip http://10.10.2.149:9089/ima/v1/file/json_msg.zip
The following example shows a POST method to create a protocol plug-in called json_msg by using cURL:
  
curl -X POST \
   -H 'Content-Type: application/json'  \
   -d  '{ 
           "Plugin": {
            "json_msg": {
             "File": "jsonmsg.zip"
            }
         }
       }
 '  \
http://127.0.0.1:9089/ima/v1/configuration/
The following shows an example response to the POST method.

{        
  "Version": "v1",
  "Code": "CWLNA6011",
  "Message": "The requested configuration change has completed successfully."
}