Adapter Tutorial

Tutorial Content:

1. Creating an Adapter
2. Configuring an Adapter
3. Add Roles/Permissions to an Adapter
4. Sample shell scripts

Create

1. Navigate to the “Adapters” tab on the sidebar or menu of the developers console
   
2. Click + Add Adapter.
   
3. Enter the name, architecture, and description for the adapter and click Create.

   Heads Up!

   Adapter names must be unique within a system!

   
   

The new adapter will now be displayed in the list of adapters defined within the selected system.

Configure

When configuring an adapter, you can add, modify, and delete adapter files. You can also modify the commands associated with the adapter. Files are optional for storing executable commands and can be downloadable. If you elect to store commands inside of files, a command to execute the file must be provided.

Add New Adapter Files

1. Navigate to the “Adapters” tab on the sidebar or menu of the developers console
   
2. Click on the adapter you want to add the file to
   
   
3. Click on “Setup adapter configuration” under Configuration
   
4. Click Files tab on each command
5. Click Upload
6. Select one or more files to add and click Open
   
   
7. Click Update Adapter
   

Additional Files

Additional files can also be added with the ‘Import’ button,

or at the bottom

This is what the Adapter page looks like after files are added:

Delete Adapter Files

Click the icon to the right of the file you want to delete

When the file is deleted, the switch will automatically set to Command. Any text in Command will remain. Make sure to click Update Adapter to save changes.

Update Adapter Files

Click on Replace to replace the file with a new file or Download to download, edit, and replace with your updated file.
Click Update Adapter

Add Permissions

CRUD (Create, Read, Update, and Delete) permissions can be added to adapters for individual roles:

1. On the individual role’s page in the Roles section
   

2. Going to settings next to ‘Adapters’ in the Adapters section and clicking Edit Permissions

Sample Shell Scripts

Deploy Command

#!/bin/bash
mkdir ShowTimeAdapter

mv start.sh ShowTimeAdapter
mv stop.sh ShowTimeAdapter
mv status.sh ShowTimeAdapter
mv deploy.sh ShowTimeAdapter
mv undeploy.sh ShowTimeAdapter
mv showTime ShowTimeAdapter

echo "ShowTimeAdapter Deployed"

The deploy command specified to execute the deploy.sh shell script would be

./deploy.sh

Start Command

#!/bin/bash
nohup ./ShowTimeAdapter/showTime > ./ShowTimeAdapter/showTime.log 2>&1 &

The start command specified to execute the start.sh shell script would be

./ShowTimeAdapter/start.sh

Note that the command takes into account the fact that the deploy script copied the start.sh file to a directory named ShowTimeAdapter. Since the shell script only contains one line, we easily could have specified the value of Start Command as

nohup ./ShowTimeAdapter/showTime > ./ShowTimeAdapter/showTime.log 2>&1 &

Stop Command

The stop command will most likely be a command that kills the adapter process, such as

ps -ef | grep showTime | grep -v grep | awk '{print $2}' | xargs kill

If a more sophisticated shutdown of the adapter is needed, shutdown logic can be incorporated into a shell script. A sample shell script, named stop.sh is as follows:

#!/bin/bash
ps -ef | grep showTime | grep -v grep | awk '{print $2}' | xargs kill

The stop command specified to execute the stop.sh shell script would be

./ShowTimeAdapter/stop.sh

Note that the command takes into account the fact that the deploy script copied the stop.sh file to a directory named ShowTimeAdapter. Since the shell script only contains one line, we easily could have specified the value of Stop Command as

ps -ef | grep showTime | grep -v grep | awk '{print $2}' | xargs kill

Status Command

#!/bin/bash
# If this script is executed, we know the adapter has been deployed. No need to test for for the "undeployed" status.
STATUS="Deployed"
if [ "ps -ef | grep showTime | grep -v grep" != "" ] ; then
    STATUS="Running"
else
    STATUS="Stopped"
fi

echo $STATUS

The status command specified to execute the status.sh shell script would be

./ShowTimeAdapter/status.sh

Undeploy Command

The undeploy command will most likely be a command that deletes an adapter specific directory and any files contained within it, such as

rm -rf ./ShowTimeAdapter

If a more sophisticated undeployment/deletion of the adapter is needed, undeploy logic can be incorporated into a shell script.

A sample shell script, named undeploy.sh is as follows:

#!/bin/bash
rm -rf ./ShowTimeAdapter

Logs Command

The logs command will most likely be a cat or tail command that displays the contents of a file, such as

cat ./ShowTimeAdapter/showTime.log

In many cases, the Logs Command will be directly dependent on the Start-up Command piping output to a file, unless the adapter is written in such a manner that it creates its own log files. If more sophistication is needed to read log files, the logic can be incorporated into a shell script.

A sample shell script, named log.sh is as follows:

#!/bin/bash
cat ./ShowTimeAdapter/showTime.log

The logs command specified to execute the logs.sh shell script would be

./ShowTimeAdapter/logs.sh

In order to prevent naming collisions resulting in overwritten files, it is recommended that an adapters files be copied to an adapter specific directory. The files can be copied using either a shell command or a shell script.If using a shell script to accomplish tasks needed for deployment, the shell script must be included as one of the adapter files in the File section of the command.A best practice would be to provide an archive/zip file containing all the files required to execute and manage an adapter. The deploy command would the simply be a shell command to extract the contents of the archive, for example:

tar -xvzf MyAdapter.tar.gz -C /MyAdapter