REST Trigger - ReceiveHTTPMessage

Use the ReceiveHTTPMessage REST trigger when creating flows that are going to be invoked by an external REST call. The ReceiveHTTPMessage trigger exposes your flow as an API, making it accessible to other apps running on TIBCO Cloud™ or elsewhere. This trigger must be configured to set up the fields for a request that the server receives from a REST client.

Note:

  • If you add or delete path or query parameters in the trigger, you must click Sync for the changes to be propagated to the flow input schema

  • REST trigger does not support authentication and authorization headers.

Trigger Settings

Field Description
Trigger Settings
Port By default, the trigger listens on port 9999. You can change this to use another open port. Do not use ports 8080 or 7777, as these ports are reserved for internal use.

Important: If the app has multiple triggers that require a port to be specified, specify a unique port number for each trigger. Two triggers in the same app cannot run on the same port.

Configure Using API Specs

While creating a REST trigger, you can configure it by uploading an API specification file.

To do this, click True (By default, it is set to False) and specify the following:

API Spec: Click Browse and then select the specification file to be used for configuring the trigger. Supported specifications are Swagger Specification 2.0 and OpenAPI Specification 3.0.

Handler Settings
Path

The resource path for the operation.

If you upload an API specification file, select a path from the drop-down list. The path parameters are parsed from the API spec file and the data types displayed are string, integer, or boolean as specified in the file.

For manual configuration, the data type for resource path is string.

By default, the path displayed here is the resource path you had entered when you created the flow. The Path field is editable if you have not uploaded an API specification file. For example, if you want to add a path parameter for a GET operation, you can do so by editing the resource path in the GET flow. If you edit the path in the Path field for a particular REST operation flow, the edited resource path applies only to the flow in which it was edited.

Two resource paths with the same base path should not contain the path parameters at the same location. For example, you cannot have the following paths in the same app:

  • /books/{ISBN}/Author/{releaseDate} and /books/{ISBN}/Author/releaseDate is considered the same from a routing perspective.

    In these two paths, the dynamic ISBN value causes a conflict during path resolution.

  • /books/{ISBN}/{releaseDate} and /books/{ISBN}/Author in the same app is not supported.

    Although the two paths seem different, when a message comes in, the router mechanism cannot determine which path to call (the one with the parameter or the one without) because the actual value has been substituted for the parameter.

  • Resource path with two different path parameters at the same URL subsection. For example, /0.6/api/account/{account}/orderhistory/{orderhistory}/branch/{branch} and /0.6/api/account/{AccountKey}/Price?ProductList={ProductList}

    In these paths even though the paths differ after the base path (/0.6/api/account/), there is a conflict when resolving the {account} and {AccountKey} values.

  • Multiple REST resources with the same base path and the same number of path parameters. For example, /resource/{id} and /resource/{id1}

  • /messages/{messageid}/comments/{commentid} and /messages/{messageid}/likes/{likeid

    where the paths differ after {messageid}.

Method The REST operation which the flow implements. Supported HTTP methods are: GET, PUT, POST, DELETE, and PATCH.
Request Type

This field is displayed only when Method is POST, PUT, or PATCH. Select one of the following types from the dropdown list:

  • application/json
  • application/x-www-form-urlencoded
  • multipart/form-data

Default: application/json

Note: If you create a Flogo app using an API specification file having Request Type as application/x-www-form-urlencoded or multipart/form-data, then you must click Sync to update the request parameters with the Flow Input.
Output Validation

When set to True, the incoming data (body, headers, and query parameters) is validated against the configured JSON schema.

Default: False

Output Settings

Field Description
Query Parameters Query parameters to be appended to the path. To add the query parameters, click and press Enter to save your changes.

  • parameterName: Name of the query parameter.

  • type: The data type of the query parameter. Supported types are string, number, and boolean.

  • repeating: Set to True if more than one value is expected for the query parameter.

  • required: Set to True if the query parameter is a required configuration. The trigger reports an error if no values are provided to the required query parameter.

Path Parameters Path parameters that are appended to the path.
Headers Header values for the trigger. To add the header parameters, click and press Enter to save your changes.

  • parameterName: Name of the header parameter.

  • type: The data type of the header parameter. Supported types are string, number, and boolean.

  • repeating: Set to True if more than one value is expected for the HTTP header.

  • required: Set to True if the header parameter is a required configuration. The trigger reports an error if no values are provided to the required header parameter.

Request Schema Enter a request schema here. This field is visible only if you selected the POST, PUT, PATCH, or DELETE method on the Settings tab.
Note:

  • For the DELETE method, specifying the request schema here is supported for manual configuration only and not when configured with Tibco Cloud Mesh and API specification.

  • If you selected application/x-www-form-urlencoded as the Request Type on the Settings tab, the default schema is set here. You can edit the default schema or specify your schema. If you specify your schema, it must be a name-value string pair.

Multipart Data

This field is displayed in place of the Request Schema field if you select multipart/form-data as the Request Type in the Trigger Settings. Click the Add rowbutton to add the parameters.

  • Name: Parameter name.

  • Type: Supported types are string, object, and filecontent.

  • Required: Check the box if the parameter is a required configuration.

  • Schema: Enter the JSON schema in this field if the Type is an object.

Note: The file content received by the trigger is converted into a byte array. This is passed to the Activity as a Base64-encoded value in an array. If you want to fetch the content of the file, coerce the first element of the array to string.

Map to Flow Inputs

Use this tab to map the trigger output to the flow input.

Reply Settings

Field Description
Configure Response Codes Use this field to configure response codes.

Default: False (See "Reply Data Schema" in this table.)

To specify a response code, select True and click . Enter the following details:

  • Code: Enter the response code.

  • Type: Select the type of response expected for the Code. Supported types are String and Object.

  • Response Body: If the Object is selected as the Type, enter the JSON schema in the  Response Body column. For String, you need not enter anything in the  Response Body column.
  • Response Headers: The header parameters for the reply are in JSON data format.
  • Actions: The actions displayed change based on the type of the response code.
    • Edit, Delete: For an Object type of response, you can edit the details or cancel it.
    • Save, Cancel: For a String type of response, you can save or cancel the changes.

The response codes is displayed on the Map from the Flow Outputs tab.

Note: The REST reply data type is by default set to data type any.
For multiple response codes, use the ConfigureHTTPResponse Activity in the flow to map Response Body and Response Headers from the REST trigger with the Input in the Activity. To configure ConfigureHTTPResponse Activity, see ConfigureHTTPResponse.

The image shows the Reply Settings with multiple response codes.

Screenshot of Reply Settings of REST trigger for multiple response codes.

Caution: If you modify the response code schema in the table, the corresponding ConfigureHTTPResponse activities within that flow do not change appropriately. This happens specifically when removing fields from the Reply Settings tab. Redo the mappings for the ConfigureHTTPResponse activities.
Reply Data Schema

Note: This field is displayed only when Configure Response Codes is set to False.

The schema is used for the reply data of the trigger. Be sure to use straight quotes for element names and values in the schema.

Map from Flow Outputs

Map the flow output to the trigger reply on this tab.

Note:

  • To update these settings for a trigger configured from the Swagger 2.0 or OpenAPI 3.0 specification, update the API specification file and upload it to the Trigger Settings. Do not update the settings as manual updates are removed.

  • If you are using a REST trigger in your app:
    The endpoint URL contains the app name only if the app has one trigger.
    The endpoint URL contains the app name and trigger name for more than one trigger.

    If you add a REST trigger to an existing app, you must reconfigure the client app.