Configure the integration

Now that you have added the HTTP integration, configure your integration. This endpoint data along with service action configuration forms the basis for creating actionable microapps.

Add Data Endpoints

Configure the data endpoints to read relevant data into the cache. Any data that we want to show to the user (or want to trigger events or actions with) must be cached.

To add a data endpoint, follow these steps:

  1. Select Data Loading.

    Add new endpoint

  2. Enter Endpoint Name and Endpoint URI.

  3. Configure Request Method.

  4. (Optional) Select + ADD PARAMETERS, and configure PATH, QUERY, OR HEADER parameters if necessary.

    Note:

    The data type you select determines the formatting of the attributes. The formatting determines the fields in microapps. Use mustache tags to reference parameter names. For example, {{parameterName}}.

  5. Select Pagination Type.

    The pagination type you must select depends on your target application integration’s API standard. Consult your target application integration’s API documentation to see what pagination method your application integration uses. HTTP Integration lets you select from the following standard pagination methods.

    • None - No pagination defined.
    • Page - Set the limit of returns per page.

      Example: https://example.com?limit=100&page=3

    • Offset - Supply two parameters, offset and limit. Offset defines the number of records to skip, limit the number of records to display per page.

      Example: https://example.com?limit=100&offset=300

    • Link - Define the pagination method to define the next page link in the body.

      Example:

       {
       “data” […]
       “next”: https://example.com?lpage=3
       }
      
    • Header Link - Similar to link pagination, but define the pagination based on the URL page header.

      Example:

       Link: <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=15>; rel="next",
       <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=34>; rel="last"
      
    • Cursor - Cursor pagination uses a unique identifier for a specific record that is used as a pointer to the next record to query to return the page of results.

      Example: https://example.com?paginationToken=BFLMPSVZ

    • OData - Select your OData version to perform pagination to OData standards.

      Set endpoint pagination type

  6. Select Test Service to check your endpoint is correctly configured.

    If the test is successful, continue with the next step. If you receive an error message, troubleshoot based on the error message you receive.

Fetch data structure

You can now create your tables in the Fetch data structure section.

  1. Select Generate Tables.
  2. Select either From API or From JSON:
    • From API - fetch the data automatically from the defined endpoint.
    • From JSON - Use From Sample JSON to paste the API if necessary, for example you have the response but cannot call the API now. (Optional) define the root path if alternate root is required from the defined endpoint. The root path must be defined in JSON pointer notation.
  3. Select Generate Tables.
  4. To set your primary key, select the Edit Attributes pencil icon and toggle the Primary Key for the attribute to be used as the primary key (for example, id). Importantly, primary key column cannot contain null values. Do not change data type to TIMESTAMP.

    Note:

    When creating a customized integration and microapp, you must always allocate a primary key to enable correct incremental loading rather than a complete overwrite when synchronizing your data.

  5. (Optional) Select Add Table and configure extra table properties as required by your desired target application and click Save. You can then reload the table structure from your API endpoint.

  6. Incremental Synchronization

    With Incremental Synchronization toggled you can set up Synchronization. That is, to download only updated records since the last data synchronization in more frequent intervals. To do this, configure how often you would like your API call to execute. Enter at least one server time parameter. Leaving without setting a synchronization schedule sets the synchronization to manual.

    Custom parameters are only required if the target application requires them. Consult your target application integration documentation when needed. If creating a custom string for synchronization you must enter in square brackets. For example [updated >=] ‘YYY-MM-DD HHmm’.

    For more information on synchronization, see Set data synchronization below.

  7. Input your base name of created tables in the Fetch data structure section and select either:
    • From API - fetch the data automatically from the defined endpoint.
    • From Sample JSON - Use From Sample JSON when to paste the API if necessary, for example you have the response but cannot call the API now.

    Set synchronization

  8. Select Add.

Your Data Endpoint is mapped, you can now set up your service actions.

Note:

After setting up and adding your endpoint, your table structure is locked. If you need to restructure you must create and configure a new data loading endpoint.

Add additional API calls

When configuring data endpoints for your application integration, you can add extra child endpoints to the original parent endpoint to enable call chaining. Once you have set up your data endpoints you can add further associated endpoints.

Follow these steps:

  1. Select Edit on the menu of integration you want to add a child call to.

    Integration edit menu

    The integration page opens.

  2. Select Add Child API Call from the Data Endpoint menu you want to add:

    Add Child API Call menu

  3. Select the parent table and define the endpoint as you did in the steps in Data Loading section above.

When defining the request method you can to either set the path to a static or column value. Your API call chain is now associated with the parent API call. Your defined parent/child endpoints are now visualized in the Data Endpoint page.

Note:

When creating your integrations it is recommended to load your data from only one endpoint rather than multiple endpoints. Where possible favor batch calls over individual endpoint calls.

Merge tables

When configuring child API calls you can optionally merge child tables with the parent table by selecting one the following options:

Select Do not merge if you do not want to merge the parent and child tables.

Select Merge as detail to fetch all tasks and requests from the system of record along with every request detail from the request and merge them, for example, if the parent and child tables are:

/request-list
{
“id”: 123,
“Title”: “Car”,
“Role”: “Order”,
“Category”: “Sales”
}

And:

/request-detail/123
{
“id”: 123,
“Title”: “Car”,
“Desc”: “Cabriolet”,
“Date”: “2020-01-01”
}

The following table is returned after Merge as detail is selected:

Id Title Role Category Description Date
123 Car Order Sales Cabriolet 2020-01-01

Select Merge as sublist to append each child table onto the parent table individually. Using the example above, merging as as sublist results in the following:

Id Title Role Category id Title Desc Date
123 Car Order Sales 123 Car Cabriolet 2020-01-01

Configuring tables

You can reconfigure table primary keys without setting up a new configuration. You do this by deleting individual table entries in the table screen, resynchronizing the table, and selecting the new primary key.

Supported time formats

HTTP integration supports the following time formats for your system of record data:

  • ISO date format
  • OData format
  • "yyyy-M-dd HH:mm:ss.SSS",
  • "M/d/yy h:mm a",
  • "M/d/yyyy h:mm:ss a",
  • "dd/MM/yy HH:mm",
  • "MMM d, yyyy h:mm:ss a",
  • "dd-MMM-yyyy HH:mm:ss",
  • "MMMM d, yyyy h:mm:ss a",
  • "dd MMMM yyyy HH:mm:ss",
  • "EEEE, MMMM d, yyyy h:mm:ss a",
  • "EEEE, d MMMM yyyy HH:mm:ss 'o''clock'",
  • "h:mm a",
  • "HH:mm",
  • "h:mm:ss a",
  • "HH:mm:ss"

Add service actions

When you have configured your HTTP integration you can then configure your service actions. With service actions you configure the writeback actions on your application integration’s system of records. You configure service actions in a similar manner to data endpoints above. As your application integration can be any number of bespoke combinations we will take a generic approach to explaining how service actions work.

To add service actions, follow these steps:

  1. Select the integration you created under Application Name.
  2. Select Service Actions and Add New Service Action.
  3. Give it an Action Name (such as Get JIRA Ticket Info) and enter the Endpoint URI path: (/rest/api/2/issue/{{issueKey}})
  4. Configure your Request Method based on your application integration’s API requirements.

    Note:

    Use mustache tags to reference parameter names. For example, {{parameterName}}.

  5. Select ADD to save the service action. You can now add extra service actions as required.

API request method

You can now configure your Request Method based on your application integration API requirements with the following components:

  • GET - Retrieve resources from the application integration SOR without modifying.
  • POST - Create a new resource in the application integration SOR.
  • PUT - Update existing resources in the application integration.
  • PATCH - Make a partial update to a resource.
  • DELETE - Delete a resource.

With following configurable API parameters:

  • Header - Define parameters included in the request header, usually related to authorization.
  • Path - Define parameters within the path of the endpoint, before the query string.
  • Query - Define parameters in the query string of the endpoint.
  • Body - Define parameters included in the request body.

Data update before action execution

(Optional) Configure data update before action execution to ensure your data is fully synchronized for your microapp end users when they action it. For example, you want to make sure the amount shown on the actionable microapp is the correct amount to approve and that it has not been updated in the time between its creation and its approval.

To set up data update before execution, follow these steps:

  1. Select the existing Data endpoint that you want to fetch the updated record from.
  2. (Optional) Enable Include child endpoints only if the child data endpoints are required to fetch the full detail of the updated record.
  3. (Optional) Extend the original Endpoint URI if it allows the update to fetch a single record. For example, if the data endpoint URI https://domain/api/items is updated to https://domain/api/items/itemId. The new endpoint URI must return the same data structure as the original one, otherwise data parsing will fail.
  4. (Optional) Extend the original request parameters with Add additional parameter if it enables filtering of a single record.

When finished with your configuration, select save.

Data update after action execution

(Optional) To ensure your data is fully synchronized after action execution, you can configure a data update to fetch fresh data from you target application system of records.

To set up data update after execution, follow these steps:

  1. Select the existing Data endpoint that you want to fetch the updated record from.
  2. (Optional) Enable Include child endpoints only if the child data endpoints are required to fetch the full detail of the updated record.
  3. (Optional) Extend the original Endpoint URI if it allows the update to fetch a single record. For example, if the data endpoint URI https://domain/api/items is updated to https://domain/api/items/itemId. The new endpoint URI must return the same data structure as the original one, otherwise data parsing will fail.
  4. (Optional) Extend the original request parameters with Add additional parameter if it enables filtering of a single record.

When finished with your configuration, select save.

Verify needed entities

Use Table to verify your current list of tables stored in the cache and filters that are applied to those tables.

You are now ready to set and run your first data synchronization unless you need to create custom relationships. For more information, see Set data synchronization.

Create custom relationship

Use the Relationships page to create a custom connection between tables in your integration. You might use this if you have multiple Base URLs and multiple integrations are required or if you want to create a custom relationship in the same integration. This is an advanced use-case and we recommend you familiarize yourself with creating microapps on a single integration before you start mapping multiple integrations.

  1. From the Manage Microapps page, select the menu next to the integration that you want to verify entities for.
  2. Select Edit and then Relationships.
  3. Select Add New Relationship.

    The Add Relationship Page Opens.

  4. You can map your primary table to your foreign table.
  5. Enter the alias you want to have.

You can now map and add additional reference columns based on the primary keys you have set up on each of your integrations.

Important:

If you delete a table, all relationships are deleted as well.

Set data synchronization

Pull data from your integrated applications to the Microapps platform so that a comparison can be made to the cache. As a best practice, full synchronization is performed every 24 hours and incremental syncs can be configured to pull every five minutes.

For complete information about synchronization rules, synchronization that does not meet its schedule and veto rules, see Synchronize data.

  1. From the Manage Microapps page, select the menu next to the integration for which you want to set synchronization.
  2. Select Synchronization.

    How to set data sync

  3. Set Full and Incremental data synchronization values.

    • Full Drops the local cache and pulls all data from the source system.

      Important:

      Running full synchronization can take a long time. We recommend running full synchronization at night or generally during off hours. You can cancel a data synchronization that is in progress at any time by selecting the X icon.

    • Incremental Pulls only changed (new and updated) records. Does not load deleted data.

      Important:

      Not all APIs support incremental synchronization.

      When you define daily or weekly synchronization, synchronization occurs randomly within the timeslot you select. For example, selecting 00-04 daily full synchronize will run a full synchronize at a randomly selected time in that period.

  4. Select Save.

Note:

You can also select the arrow icons to run the integrations on demand if necessary.

Show integration logs

Use Integration Log to view a history of changes categorized by severity. Use this for troubleshooting issues with your integration. For example, if you see that the synchronization failed, check the integration logs to see why. Or if expected cards are not showing, check the integration logs to see if the synchronization occurred.

How to find Integration Logs

  1. From the Manage Microapps page, select the menu next to the integration that you want to view integration logs for.
  2. Select Integration Logs.
  3. Review the entries, and select the menu to filter by Errors if necessary.

Export integration configurations

You can export your integration configurations. All credentials are discarded. This includes passwords and client details. Only the configuration that is stored in the Microapps server is exported. For example, the export keeps your user name but not your Password, and also the export keeps your OAuth configuration but not the client secret.

  1. From the Manage Microapps page, select the menu next to the integration that you want to export.
  2. Select Export Configuration.

    The service.mapp file downloads.

Where to go next

Now that you have created and configured your custom integration, build your own microapps to deliver the best end-user experience that meets your needs and streamlines daily workflows. For more information, see Create microapps.

Configure the integration