Creating and updating a protocol plug-in

System administrators can import a new or updated protocol plug-in by using the Eclipse Amlen REST API PUT method. System administrators can then create the protocol plug-in by using the Eclipse Amlen REST API POST method.

To run a protocol plug-in, you must deploy the plug-in in Eclipse Amlen. 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.

Import the plug-in .zip file to Eclipse Amlen by using the Eclipse Amlen REST API PUT method with the following Eclipse Amlen file URI:

http://<admin-endpoint-IP:Port>/ima/v1/file/<filename>
To create or update an imported protocol plug-in, use the Eclipse Amlen REST API POST method.
1. Use the following Eclipse Amlen 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 Eclipse Amlen 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.
Stop and restart the Eclipse Amlen protocol plug-in server process. Use the Eclipse Amlen 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 Eclipse Amlen 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 Eclipse Amlen 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.

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."
}