Updating a protocol plug-in properties file

Update an installed protocol plug-in properties file by using the IBM® Watson IoT Platform - Message Gateway REST API POST method.

Before you begin

To update a protocol plug-in properties file, the plug-in with which it is associated must previously have been deployed 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

To update the protocol plug-in properties file, 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>": {
      "PropertiesFile": "string",
      "Overwrite": true|false
      }
   }
}
```
  Where:
  
  NameOfPlugin
  
  Required.
  
  Specifies the name of the protocol plug-in that is associated with the properties file. This can be found in the plugin.json configuration file if it exists.
  
  The maximum length of the name is 256 characters.
  
  PropertiesFile
  
  Required.
  
  Specifies the protocol plug-in properties file name that you want to update. 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
  
  Required if the protocol plug-in is already installed.
  
  Specifies whether any existing protocol properties file with the same name is overwritten.
  
  The default value is false.
Restart the IBM Watson IoT Platform - Message Gateway 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
```
The plug-in properties file can be updated at any time, but the update is not effective until the IBM Watson IoT Platform - Message Gateway plug-in server process is restarted.

Note: If you need to remove the plug-in properties file from your system, you can either upload an empty properties file and overwrite the existing properties file, or delete and reinstall the protocol plug-in but do not specify a plug-in properties file on the protocol plug-in configuration.

Example

The following example shows the POST method to update the plug-in properties file called pluginprops.json:

  
curl -X POST \
   -H 'Content-Type: application/json'  \
   -d  '{ 
           "Plugin": {
            "json_msg": {
             "PropertiesFile": "pluginprops.json"
             "Overwrite": true
            }
         }
       }
 '  \
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."
}

The following example shows restarting the protocol plug-in server:

  
curl -X POST \
   -H 'Content-Type: application/json'  \
   -d  '{ 
           "Service": "Plugin"
        }
 '  \
http://127.0.0.1:9089/ima/v1/service/restart

The following example shows an example response to the POST method to restart the protocol plug-in server:


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