REST API: Creating a REST API Rule

About this task

SOTI Snap can leverage several REST APIs to give standardized, scalable, and stateless communication between SOTI Snap apps and remote data sources.

Data Connection Rules view, REST API tab
SOTI Snap can exchange data with any of the following sources:
  • REST Service: Exchanges data between a REST Service and a SOTI Snap app.
  • Server-Side Script: Exchanges and manipulates data via a server-side JavaScript script with a SOTI Snap app.
  • SOTI Connect: Exchanges data between a SOTI Connect instance and a SOTI Snap app.
  • SOTI MobiControl: Exchanges data between a SOTI MobiControl instance and a SOTI Snap app.
  • SOTI XSight: Exchanges data between a SOTI XSight instance and a SOTI Snap app.

About this task

Set up a rule to exchange data between a REST API connection for one of the supported sources and your app:

Step 1: Create a Connection

  1. In the Canvas, select the Data Connection Rules tab, then the REST API tab.
    Data Connection Rules view, REST API tab
  2. Select New REST API Rule to launch the Create REST API wizard.
  3. Enter a name for the destination.
  4. Select one of the supported sources from the available sources. Select Next.
    Note: Each data connection name must be unique within the app.
  5. Depending on the destination selected, select Play Demo to watch a video explaining how to set up the rule.
  6. Select Next.
  7. For the selected REST API destination, enter the following information:
    REST API Procedure
    REST Service
    Note: Check you have access rights to the external tool you want to connect to SOTI Snap.
    Create REST Connection required information
    • Name: Enter the name of the REST service.
    • Base URL: Enter the URL starting point for the REST service.

      For example, https://server/service/api

    • Enter REST Service credentials: Turn on if you require credentials for this connection.

      If so, give the Username and Password for the service.
    Server-Side Script In Code Window, enter the JavaScript code:

    Example of Code Window with the script entered

    SOTI Connect
    • Account Name: Enter a name for the SOTI Connect account.
    • Base URL: Enter the base URL of the SOTI Connect instance API endpoint. For example, https://server/connect/api.
    • Token Endpoint: Non-editable
    • Username: Enter a username for an account with access to the SOTI Connect server.
    • Password: Enter the password for the user account.
    • Client ID: Enter the client ID generated when you installed SOTI Connect.
    • Client Secret: Enter the client secret generated when you installed SOTI Connect.
    SOTI MobiControl
    • Account Name: Enter a name for the SOTI MobiControl account.
    • Base URL: Enter the base URL of the SOTI MobiControl instance API endpoint. For example, https://server/mobicontrol/api.
    • Token Endpoint: Non-editable
    • Username: Enter a username for an account with access to the SOTI MobiControl server.
    • Password: Enter the password for the user account.
    • Client ID: Enter the client ID generated when you installed SOTI MobiControl.
    • Client Secret: Enter the client secret generated when you installed SOTI MobiControl.
    SOTI XSight
    Tip: You can send data from an app to the SOTI XSight API for a new ticket creation request.
    • Account Name: Enter a name for the SOTI XSight account.
    • Base URL: Enter the base URL of the SOTI XSight instance API endpoint. For example, https://server/xsight/api.
    • Token Endpoint: Non-editable
    • Username: Enter a username for an account with access to the SOTI XSight server.
    • Password: Enter the password for the user account.
    • Client ID: Enter the client ID generated when you installed SOTI XSight.
    • Client Secret: Enter the client secret generated when you installed SOTI XSight.
  8. Execute the following procedure to proceed to connection definition:
    REST API Procedure
    REST Service
    1. Select Finish.
    2. Select Next.
    Server Side Script N/A
    • SOTI Connect
    • SOTI MobiControl
    • SOTI XSight
    1. Select Test Connection to check the connection works.
    2. Select Next.

Step 2: Define the Connection's Use

  1. Follow the corresponding procedure to customize and verify your selected connection:
    REST API Procedure
    Server Side Script
    • If required, select Add Parameter to give key-value pairs expected by the server-side script.

      In the Enter Parameter dialog box, select to add more key-value pairs as needed.

    • Select Test Connection to check there are no syntax errors.

      Result: A message above the code window appears, indicating the success of the connection. The Code Window shows any syntax errors found.

    • Select Next. Response displays the data received from the JavaScript code.
    • If satisfied with the response, select Next.
    • REST Service
    • SOTI Connect
    • SOTI MobiControl
    • SOTI XSight
    1. From REST Service URL / SOTI Connect Service URL / SOTI MobiControl Service URL / SOTI XSight Service URL:
      1. Select the method for exchanging data in this connection.
        • GET: Request data from the connected REST service.
        • POST: Submit new data to the connected REST service for processing.
        • PUT: Update or replace data in the connected REST service.
      2. Enter the REST service URL / SOTI Connect service URL / SOTI MobiControl service URL / SOTI XSight service URL
    2. Optional:
      Note: If you selected a POST method, see the SOTI Connect or SOTI MobiControl or SOTI XSight Swagger API documentation to locate the POST request for sending data.
      • From Request Details, complete the Key, Value, and Response parameters as required for the following:
        Headers Give any header information expected by the API for authentication.
        Body Give the request parameters you want to use to send information at runtime.

        Select one of the following formats:

        • Form, select X-Www-Form-Urlencoded (Encodes data before sending it to the server)
        • JSON, select Raw (Key, Value, and Response parameters are not required. Send data directly as a string, without any encoding or transformation.)
        Query Strings Give query strings key-value pairs to send specific app data.
    3. Select Test Connection to check the connection works.
      Important: If you selected a POST method, be aware you are writing data to the connected service.
      Successful tests generate a response which appears below the Request information.
    4. Select Next.
  2. Review the connection summary. Select Finish if satisfied with the results, or select Back to make changes.

Results

Your new connection lists in the Data Connection Rules table of the REST API tab, and you may use it in your app.

What to do next

Add the data connection to your app. On a widget that supports Events, add the Invoke Rest API action to add this connection. See Map REST API Fields to Widgets .

Learn more about events and actions at Events and Actions.