Modules

Modified on Sun, 19 Mar 2023 at 08:41 PM

Modules are the key component of your inMultifamily app. They are basically wrappers around specific app/service functionality, which is exposed via an API endpoint.

There are three basic types of modules: Action, Search, and Trigger (polling).

Action	Use if the API endpoint returns a single response. Examples are Create a lead, Delete a lead or Get a lead.
Search	Use if the API endpoint returns multiple items. An example is List leads that will find specific leads according to search criteria.
Trigger	Use if you wish to watch for any changes in your app/service. Examples are Watch a New lead, which will be triggered whenever a new lead has been added to the library.

Note: inMultifamily works with 6 types of modules, read more about them

Creation of a new module

To create a new Module, click on the tab MODULES. The list of all modules your app consists of, will be shown (empty for now). Click the large button with the plus sign and choose Create a new Module.

A dialog will pop up, where you can name your module, choose its type, and provide some description. Fill the dialog as shown and click

Save

Make sure the tab Communication is active and replace the content of the text area with the following JSON and save the changes (Ctrl+S):

{
    "url": "/helloworld"
}

The url key specifies the API endpoint path. The URL will be joined with baseUrl specified earlier to produce the full URL of the API endpoint: http:yourcompany.com/api/v1/helloworld

In order to use baseUrl specified in the base, the URL should start with /. If the URL doesn't start with /, the baseUrl doesn't come into use, and only the content of url is used instead.

Click the tab Mappable parameters. The JSON on this tab enables you to specify the parameters of your module that will appear in the module settings panel. Our module does not require any parameters, so erase the content between the square brackets, leaving just empty square brackets and save the changes (Ctrl+S):

[]

We will guide you through the process of testing your newly created module.

To begin, launch a new browser tab and sign in to your inMultifamily account. Once logged in, navigate to the left main menu and select Scenarios. Proceed to create a new scenario.

Afterward, click on the undefined "questionnaire" module, which will display a list of available apps. Locate your newly created app by entering its name, "My App," into the search bar. Once you've found your app, click on it to view its modules, including the recently added "Hello World" module. Select this module to proceed.

Upon selecting the module, an empty settings panel will appear with a message stating, "There are no configurable options for this module." This indicates that you have successfully accessed your newly created module within the inMultifamily platform.

We will now demonstrate how to close the settings panel, execute the scenario, and view the results of your new module.

First, close the module settings panel by clicking the appropriate button or area. Next, initiate the scenario by selecting the "Run" option. As the scenario progresses, you will notice bubbles appearing above the module. Click on these bubbles to access a panel containing details about the processed data bundles.

If you have followed this tutorial correctly, you should now see the output generated by your new module displayed in the information panel. This output serves as confirmation that your module has been successfully integrated and is functioning as expected.

Perfect! You just learned how to create a new module and make it work. But we can make it better! We can make it more user friendly. Continue reading below.

We will now discuss configuring the module interface. Given our understanding of the output structure, we can define the Interface directly, eliminating the need to run the module beforehand to determine the output's format.

The example below illustrates a list of available parameters that can be mapped from the Shopify > Watch Orders module. Take note that the Shopify module has not yet been executed, as indicated by the absence of a bubble display. This demonstrates that it is possible to set up the scenario without prior execution of the module to learn the output's structure.

In the display section containing the output, select the button highlighted below and opt for the Download Output Bundles choice.

Subsequently, a fresh panel will emerge, presenting the initial response from the endpoint. Copy the text onto your clipboard.

Return to the tab containing your application and confirm that you are within the Hello World module's settings. Choose the INTERFACE tab, where you will find a JSON snippet displayed:

[
    {
        "name": "id",
        "type": "uinteger",
        "label": "User ID"
    }
]

In the top right corner, select the Options button and opt for the Generator choice.

A fresh panel will emerge. In this panel, paste the JSON you previously copied to your clipboard and press the Generate button.

A new data structure will be generated. Copy it to your clipboard and close the panel.

Old Code:

[

    {

        "name": "id",

        "type": "uinteger",

        "label": "User ID"

    }

]

Replace with New Code:

[

  {

    "name": "result",

    "type": "text",

    "label": "Result"

  }

]

Whenever you change INTERFACE in a module, you need to refresh your scenario in order to see the changes.

Perfect! You just learned, how to work with interface and automatically prepare a list of expected parameters from the module's output. Now, let's make it harder!

Adding mappable paramaters

Within inMultifamily modules, it is possible to specify the data that should be transmitted to the API, enabling the creation of a new entry or the definition of returned information. The Demo API endpoint, /helloworld, accepts two parameters: greeting and name. To view the API response in your browser, click on the subsequent link:

The api should return the following JSON response:

{"result":"Hi, Johny!"}

Let's make our Hello World module adaptable by incorporating the 'greeting' parameter. Return to the Mappable Parameters tab, replace the empty square brackets with the JSON provided below, and save your changes using Ctrl+S:

[
    {
        "name": "greeting",
        "type": "text",
        "label": "Greeting"
    }
]

This JSON indicates that the module will include a single text-type parameter named Greeting. Further information on parameters can be found in the Parameters documentation. Transition to your scenario and refresh the browser window using F5.

Click on the Module to bring up its settings panel. You will now see a text field labeled Greeting. Enter "Hi" into this field:

Whenever you change MAPPABLE PARAMETERS in a module, you need to refresh your scenario in order to see the changes.

Press OK and run the scenario. Though, if you click the bubbles above the module to pop up the panel with information about processed bundles, the module’s output will be identical as in the previous run.

Observe that there is no parameter named "greetings" being transmitted. This occurs because we must delineate the request structure within the module. More specifically, we need to relay the content of the greeting parameter to the API.

Return to the MAPPABLE PARAMETERS tab and select the COMMUNICATION tab. To convey the 'greetings' parameter to the API, there are two alternatives available:

You can either add the parameter to the url key:

{
    "url": "/helloworld?greeting={{parameters.greeting}}"
}

Alternatively, you can introduce a new key called 'qs' (query string) and incorporate the parameter within it:

{
    "url": "/helloworld",
    "qs" : {
        "greeting": "{{parameters.greeting}}"
    }
}

Save your modifications using Ctrl+S, navigate to your scenario, and execute the scenario.

Click on the bubbles situated above the module to display the panel containing information about processed bundles, where you should observe the altered module's output:

You can now practice your skills and try to add a parameter Name to your Hello World module.