Building a Custom Integration
Siemplify users can create custom integrations inside the Siemplify IDE with the same structure as Siemplify commercial integrations. The custom integrations will appear in the Marketplace and can be configured for different environments so they can be used in Playbooks, manual actions and remote agents. They can also be imported and exported as with other IDE items.
In this How To we will build a custom integration for the Armis product and create a Manager along with a Ping action. Knowledge of Python and object oriented programming is assumed for this tutorial.
Creating the Custom Integration in the IDE
From the IDE screen click the + icon in the upper left hand corner to add a new IDE item. Select the Integration radio button and give the integration a name.
The integration will be created and listed on the left hand side with a cog icon that designates it as a custom integration.
Clicking on the Cog Icon will bring up the Integration Settings where the Icon, Description, Python Dependencies and Integration Parameters can be defined. In the following screenshot, an image has been uploaded (this image will appear in the Marketplace with the integration), a brief description has been added and two parameters have been defined. There are no Script Dependencies that need to be added because the only non-standard Python library that will be utilized in this integration is the
requests library which is already installed on the system.
Creating the Manager
Managers are not strictly necessary for an integration to function, but they are a great idea, especially for integrations that involve third party tools. Managers are essentially wrappers that contain the API logic for the third party tool. Managers should not have any imports from the Siemplify SDK. Once the Manager is created, it can be imported as a module into Connectors, Actions and Jobs and its methods can be utilized.
To create the custom manager:
- In the IDE screen, click the plus icon on the top left.
- Select Manager and select the Armis integration, and name the Manager.
- Edit the script as it appears below.
Parameters, Marketplace Configuration and the Ping Action
The parameters defined in the Integration Settings will appear in the Marketplace Configuration for the Integration.
After entering the correct credentials, click the Save button and then the Test button.
The Test button will fail and display a red X because no Ping action has been configured for this integration.
The logic of the Ping action should be something like a successful authentication. In the Siemplify IDE, create a new Action in the Armis Integration with the name Ping. Utilizing the ArmisManager and its auth method, the Action will look like the following:
Enable it by clicking the switch to the left of the integration name (it’s already enabled in the screenshot above as shown by the green switch in the upper left hand corner) and Save it. In the Action above, the API Root and the API Token are being imported from the Marketplace Configuration and being passed to the
ArmisManager. The Manager then calls its
auth method and if there are no errors, the Test button will return a green checkmark.
Just to verify that the logic of the Action is sound, we can enter incorrect credentials, click Save and then run the Test again. The screenshot below shows an obvious credential error.
Viewing your Custom Integration in the Marketplace
Navigate to the Marketplace and search for the custom integration you created. If you didn’t create an image during the initial configuration, then the default custom image will be assigned to it. Note that Marketplace updates will not override or delete any custom integrations. In the screenshot below, the integration has two Actions that have been created for the integration.
Exporting/Importing in the IDE
Use the Export / Import buttons to back up or share the integration with other parties.
Exporting the integration will download a ZIP file with the relevant Definition, Script, and other configuration files. Crucially, as of Siemplify 5.2, the ZIP will not contain the Managers folder with the Manager, so this must be exported manually.
Importing integrations is a similar process. Simply upload a valid ZIP file that contains the proper folder structure and the integration will appear in the IDE and Marketplace.
Siemplify SDK Documentation
The Siemplify IDE contains a helpful link to the Siemplify SDK documentation which can also be found here.
Need more help with this?
Click here to open a Support ticket