Skip to main content

Orchestrate Next Gen

Build a Sample App

This section guides you through the step-by-step procedure to:

  1. Create an app called Hello World.

  2. Create an action in the app to return Hello World.

  3. Create an action in the app to receive input from the user and return the same as the output.

Before you Start

Ensure the following before building a custom app:

  • You must have a basic understanding of Python (3.6 or later) classes, functions, packages, and data structures.

  • You will need a PythonIDE to view the app on your local machine. While we recommend using Python IDE, apps can also be written using text editors such as Sublime Text or Notepad++.

    Recommended: VS code or PyCharm

  • Identify the use case for the app you are building.

Understand the App Interface
updated-custom-app.png

Use the following components to start building your first app: 

  • Python-based Interactive Development Environment (IDE) on the left pane: Write your code, and define classes and methods based on the use case of the app you need to build.

  • App Details on the right pane: Define the app overview, and review the actions and other configurations.

Note

You must sync the data between the two panes whenever you create or modify the app. To sync data from the left pane to the right pane, click the update.png icon in the upper-right corner of the editor. You cannot sync from the right pane to the left.

Understand the usage of the following files:

  • connector.py file: This predefined template functions as the equivalent of main.py, which is executed.

  • requirements.txt file: Specify any advanced functionalities or third-party libraries you want to use. List the libraries and their versions here, and they will be installed for you.

  • _init_.py: This file indicates to the Python interpreter that a directory contains code for a Python module. Since all apps function as Python modules, the __init__.py file is essential when creating a connector.

    Important

    Do not delete the _init_.py and connector.py files.

Steps to Build an App

Follow the steps in this procedure to build a simple “Hello World” app. In Orchestrate, click the Main Menu and select Apps. On the Apps landing page, click Create New App on the upper-right corner of the screen.

Step 1: Create a HelloWorld app with two actions 

To create the HelloWorld app, update the connector.py file with the following changes:

  1. Define your class name. Enter your app name followed by the term “Connector”. Make sure you follow this format. For example, HelloWorldConnector

    Note

    Use the name and capitalization consistently across the connector.py file. Capitals are used to differentiate between the words in the app builder.

  2. Pass the _init_ method. Remove all the parameters and pass this method as follows:

    Note

    Do not delete **Kwargs while editing the code in the connector.py file

    def __init__(self, **kwargs):
        """
        description: init function
      
        """
        pass

  3. Pass the test_connection method. Replace the authentication code lines with return True as shown below, as we are building a simple “HelloWorld” app without authentication. In general, you can use this method to define the authentication methods to connect to the endpoint of the app.

    def test_connection(self, **kwargs):
        """
        description: function used for authenticating credentials
        return: True/False
        """
            return True

  4. Remove the auth method, as we are not providing any authentication logic for our “HelloWorld” app.

  5. Remove the request_handler method as we are not making any request calls.

  6. Define the first action that you want the app to perform. In our case, we want to return “Hello World”, so this does not require any input parameters.

    1. Provide a name for your action in the following format: Example: action_hello_world

      Note

      All methods that begin with action_ are recognized as actions within the app. If a method does not follow this naming convention, it will not be visible in the App UI.

    2. The HelloWorld app does not require any input parameters. Specify the values that must be returned as follows:

      def action_hello_world(self, **kwargs):
       return {"result": "Hello World", "execution_status": "SUCCESS"}

  7. Define other parameters as required. In this case, our next action is to take input from the user and return the input.

    1. Provide a name for your action in this format: Example: action_return_input

    2. Define one input parameter that accepts a string-based user input and returns the same input as follows:

      def action_return_input(self, user_input: str, **kwargs):
       return {"result": user_input, "execution_status": "SUCCESS"}

Step 2: Synchronize Data 

Click the update.png icon on the upper-right corner of the Python IDE to synchronize the data between the IDE and the App Details pane. 

Step 3: Configure App Details 

  1. In the App Details > App Information section, enter the following details:

    • App Name: Enter a relevant App name. For example, Hello World.

    • Python Class Name: View the Python class name of the app. The class name is generated based on the app name.

    • App Version: Enter the App Version. For example, 1.0.0, since this is the first version of the app.

    • Supported API Versions: Enter supported API versions. As we are not using any API calls for the basic “Hello World” connector, enter NA for the API version.

    • App Logo: Upload a logo for the app, which will be displayed in the AppStore

    • App Description: Enter an app description that will be useful to understand the use case of this app. For example, This is a test app and returns Hello World and user input.

    • Categories: Choose a relevant category for the app. For example, IT Services.

    • Link to Documentation: Add a link to the documentation for this app, if it exists.

  2. In the App Configuration Parameters section, edit the parameter and enter the following details:

    • Field Identifier: View the field identifier of the configuration parameter.

    • Field Title: Enter a title for the parameter.

    • Field Type: Select the field type for the parameter. For example, Text.

    • Field Description: Enter a description for the parameter.

    • Mandatory Parameter: Select the checkbox to mark the parameter as mandatory. Click Update.

    Skip the App Configuration Parameters section, as we do not need any authentication methods in our example.

  3. In Actions, edit existing actions or create a new action and enter the following details:

    • Action Identifier: Enter an action identifier for the action.

    • Action Name: Enter a name for action. For example, in our case, it will be hello world.

    • Action Description: Add a description for reference.

    • Accepted Parameters: Enter the input parameters required to run the action. Enter details such as Field Title, Field Identifier, Field Type, and Field Description. Select the Mandatory Parameter checkbox if the parameter is required to run the action. For the HelloWorld app, the parameter user_input for the second action action_return_input will be mandatory.

    • Return Values: Click +Value to add return values and enter details such as Title, Data Source, and Value Description.

    Click Update.

  4. Enable the Active toggle and Click Save. The app gets listed on the My Apps page.

  5. Search for the app you have just created. For example, HelloWorld

Step 4: Create a New Instance 

  1. Create or define an instance to execute the actions of the app. To do this, launch the app you just created and select the Instances tab.

  2. Click the plus icon to create a new instance icon for the selected version.

  3. Provide an instance name and an expiration date, and click Create.

For more information on how to create an instance, see Add Instances.

Step 5: Run App 

After you have created the app and specified an instance, you can now run the app.

  1. Click the ellipses on the top right of the page, and select Edit App.

  2. Click the Run icon on the IDE to execute each action before you use this app in a Playbook.

  3. To test an action, select the instance and the action name, and click Test.

    Note

    It is important you test each action of the app and ensure that the status is displayed as SUCCESS.

  4. If all the actions are successfully executed, you can turn on the toggle status of the app to Active on the top right of the page, and use this app in a Playbook.