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 by other apps running on either 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 make changes to the trigger such as add or delete path or query parameters, be sure to click Sync for the changes to be propagated to the flow input schema.

Trigger Settings

Field Description
Trigger Settings
Port By default, the trigger listens on the port 9999. You can change this to use another port that is open.

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. If the API specification changes, you can merge the changes into an existing app by uploading the specification file again.

To do this, click True 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.

Default: False
Secure Connection By default, it is set to False. If you set this field to True, you can create a secure endpoint by providing Server Key and CA or Server Certificate.

Server Key - A PEM encoded private key file

CA or Server Certificate - A PEM encoded CA or self-signed server certificate file

Handler Settings
Method The REST operation which the flow implements, for example GET, PUT, POST, or DELETE.
Request Type

This field appears only when Method is POST or PUT. Select one of the following types from the drop-down 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 the Sync button to update the request parameters with the Flow Input.
Path

The resource path for the operation. If you upload an API specification file, select a path from the drop-down list.

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 is applicable only to the flow in which it was edited.

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

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

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

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

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

  • Resource path with two different path parameters at the same URL sub-section. 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 same base path and 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}.

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 the button 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 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 the button 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 header parameter is a required configuration. The trigger reports an error if no values are provided to the required header parameter.

Request Schema Request schema for the trigger. Be sure to use straight quotes for element names and values in the schema.
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 row button to add the parameters.

  • Name: Name of the parameter.

  • 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 object.

Map to Flow Inputs

This tab allows you to map the trigger output to flow input.

Reply Settings

Field Description
Configure Response Codes Allows you to configure response codes.

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

To specify a response code, select True and click the button. 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 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 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 appear in the Map from Flow Outputs tab.

Note: The REST reply data type is by default set to data type any. To configure the reply to an explicit data type, see "Configuring the REST Reply" section in the TIBCO Flogo® Enterprise User's Guide.
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 appears only when Configure Response Codes is set to False.

The schema 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 Swagger 2.0 or OpenAPI 3.0 specification, make changes in the API specification file and upload it in the Trigger Settings. Do not update the settings as manual updates are removed.