Generate An OAS Document For Request/Reply Maps

In TIBCO Scribe® you can design a Request/Reply Event Map that parses an inbound message from another application and sends back a response to that application. In some applications, you can quickly configure the format of a message to send to TIBCO Scribe® by pasting in a URL requesting an OAS document, instead of entering the format manually. The TIBCO Scribe® API supports generating OAS Version 2.0 documents for a single Request/Reply Map, all Request/Reply Maps in a Solution, or all Request/Reply Maps in an Organization.

In TIBCO Scribe®, the first Block in a Request/Reply Map, Wait For Request, generates an endpoint URL to which messages can be sent and from which OAS documents can be generated. To locate the endpoint URL, navigate to your Request/Reply Map, open the Wait For Request Block Properties dialog, and copy the endpoint from the General tab.

In the Wait For Request Block Properties dialog on the Request tab, you define how the inbound message is parsed by listing the field name and data type of each field expected in the message.

See Defining An Event Request/Reply Map and Request/Reply Map Example in the TIBCO Scribe® Help for details on creating a Request/Reply Map.

OAS Documentation Considerations

  • Only OAS Version 2.0 is supported. See the OAS 2.0 Specification for more information.
  • Only enabled and complete Request/Reply Maps are supported.
  • Request/Reply Maps in disabled Solutions are ignored.
  • If you are documenting an existing Request/Reply Map, you may need to open it and save it again to enable this feature.
  • If/Else Blocks are ignored. The content is provided, however it is not generated as a conditional. This is a limitation of OAS 2.0.
  • Multiple Blocks at the same hierarchical level with the same entity name are merged.
  • Set of data types is limited. See Data Types in the OAS Specification for more information.
  • All objects are returned as arrays.
  • Can be returned in either JSON or YAML based on the Accept header parameter (application/yaml).

Generating The Documentation

The process for generating an OAS document varies depending on whether you want it to include a single Request/Reply Map, all Request/Reply Maps in a Solution, or all Request/Reply Maps in an Organization. The URL used for each of these scenarios is different and must be updated manually. Refer to one of the following sections for step-by-step instructions:

Single Request/Reply Map

  1. In TIBCO Scribe®, navigate to your Request/Repy Map, open the Wait for Request Block, and copy the endpoint URL of the Request/Reply Map shown at the bottom of the General tab.

    Example: https://endpoint.scribesoft.com/v1/orgs/7505/requests/1978?accesstoken=62204c80-6a52-4bfc-99b3-1f28025146d5

  2. Paste the URL into a text editor.
  3. Modify the URL and insert /api-docs as shown below to request the OAS document.

    Example: https://endpoint.scribesoft.com/v1/orgs/7505/requests/1978/api-docs?accesstoken=62204c80-6a52-4bfc-99b3-1f28025146d5

    You can append &oasversion=2 to the URL to specify OAS Version 2.0, however that is not required since only OAS Version 2.0 is supported.

  4. Paste the updated URL into the correct message configuration area for the application you are configuring to send messages to TIBCO Scribe®. The application requests the OAS document from the TIBCO Scribe® API and imports it. Depending on the application you are configuring, there may be additional steps. Refer to the Help or User Guides for the application for configuration information.

All Request/Reply Maps In A Solution

  1. In TIBCO Scribe®, navigate to one of your Request/Repy Maps, open the Wait for Request Block, and copy the endpoint URL of the Request/Reply Map shown at the bottom of the General tab.

    Example: https://endpoint.scribesoft.com/v1/orgs/7505/requests/1978?accesstoken=62204c80-6a52-4bfc-99b3-1f28025146d5

  2. Paste the URL into a text editor.
  3. In TIBCO Scribe®, close the Map to display the Solution Edit page for the Solution containing your Request/Reply Maps.
  4. In the browser address bar, locate and copy the solutionId portion of the URL from the ampersand (&) to the end of the ID.

    Example: https://app.scribesoft.com/#!/solutioneditevent?orgId=7505&solutionId=35422f62-0942-4710-9125-ef01a20c033a

  5. Open the text editor with the Map URL and append the copied text to the Map URL.

    Example: https://endpoint.scribesoft.com/v1/orgs/7505/requests/1978?accesstoken=62204c80-6a52-4bfc-99b3-1f28025146d5&solutionId=35422f62-0942-4710-9125-ef01a20c033a

  6. Modify the URL as follows:
    1. Remove the Map ID immediately following the requests/ section of the URL. This causes all Request/Reply Maps in the Solution to be selected. In this example the Map ID is 1978.

      Example Before Edit:

      https://endpoint.scribesoft.com/v1/orgs/7505/requests/1978?accesstoken=62204c80-6a52-4bfc-99b3-1f28025146d5&solutionId=35422f62-0942-4710-9125-ef01a20c033a

      Example After Edit:

      https://endpoint.scribesoft.com/v1/orgs/7505/requests/?accesstoken=62204c80-6a52-4bfc-99b3-1f28025146d5&solutionId=35422f62-0942-4710-9125-ef01a20c033a

    2. Insert api-docs into the URL as shown below to request the OAS document.

      Example: https://endpoint.scribesoft.com/v1/orgs/7505/requests/api-docs?accesstoken=62204c80-6a52-4bfc-99b3-1f28025146d5&solutionId=35422f62-0942-4710-9125-ef01a20c033a

      You can append &oasversion=2 to the URL to specify OAS Version 2.0, however that is not required since only OAS Version 2.0 is supported.

  7. Paste the updated URL into the correct message configuration area for the application you are configuring to send messages to TIBCO Scribe®. The application requests the OAS document from the TIBCO Scribe® API and imports it. Depending on the application you are configuring, there may be additional steps. Refer to the Help or User Guides for the application for configuration information.

All Request/Reply Maps In An Organization

  1. In TIBCO Scribe®, navigate to one of your Request/Repy Maps, open the Wait for Request Block, and copy the endpoint URL of the Request/Reply Map shown at the bottom of the General tab.

    Example: https://endpoint.scribesoft.com/v1/orgs/7505/requests/1978?accesstoken=62204c80-6a52-4bfc-99b3-1f28025146d5

  2. Paste the URL into a text editor.
  3. Modify the URL and remove the Map ID immediately following the requests/ section of the URL. This causes all Request/Reply Maps in the Organization to be selected. In this example the Map ID is 1978.

    Example Before Edit:

    https://endpoint.scribesoft.com/v1/orgs/7505/requests/1978?accesstoken=62204c80-6a52-4bfc-99b3-1f28025146d5

    Example After Edit:

    https://endpoint.scribesoft.com/v1/orgs/7505/requests/?accesstoken=62204c80-6a52-4bfc-99b3-1f28025146d5

  4. Insert api-docs into the URL as shown below to request the OAS document.

    Example: https://endpoint.scribesoft.com/v1/orgs/7505/requests/api-docs?accesstoken=62204c80-6a52-4bfc-99b3-1f28025146d5

    You can append &oasversion=2 to the URL to specify OAS Version 2.0, however that is not required since only OAS Version 2.0 is supported.

  5. Paste the updated URL into the correct message configuration area for the application you are configuring to send messages to TIBCO Scribe® to import the definition. The application requests the OAS document from the TIBCO Scribe® API and imports it. Depending on the application you are configuring, there may be additional steps. Refer to the Help or User Guides for the application for configuration information.

View Or Modify Contents Of An OAS Document

If you need to see or modify the contents of a TIBCO Scribe® OAS Document, you can use the URLs created in the sections above in an application that allows you to send API requests.

  1. Open an application that allows you to send API requests, such as PostMan.
  2. Use one of the modified URLs in the API application to send a request to the TIBCO Scribe® API. The API returns a response similar to the example shown below these steps.
  3. You can paste the contents of the response into the application you are configuring instead of pasting the URL. This may be helpful if you need to modify the contents in any way.
{
    "swagger": "2.0",
    "info": {
        "title": "RR Tutorial Map",
        "description": "Send a request to be processed by a Request Reply Map",
        "version": "1.0.0"
    },
    "host": "endpoint.scribesoft.com",
    "basePath": "/v1",
    "schemes": [
        "https"
    ],
    "consumes": [
        "application/json"
    ],
    "produces": [
        "application/json"
    ],
    "paths": {
        "/orgs/7505/requests/1978": {
            "post": {
                "tags": [
                    "Request Reply"
                ],
                "summary": "RR Tutorial Map - Post Request",
                "parameters": [
                    {
                        "in": "query",
                        "name": "accessToken",
                        "description": "Event Solution Access Token.",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "in": "body",
                        "name": "scribeWaitForRequestObject",
                        "description": "",
                        "required": true,
                        "schema": {
                            "type": "object",
                            "properties": {
                                "firstname": {
                                    "type": "string"
                                },
                                "lastname": {
                                    "type": "string"
                                },
                                "companyname": {
                                    "type": "string"
                                },
                                "email": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "reply": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "message": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request."
                    },
                    "404": {
                        "description": "Not Found."
                    },
                    "415": {
                        "description": "Unsupported Media Type."
                    },
                    "429": {
                        "description": "Rate Limit Exceeded."
                    },
                    "500": {
                        "description": "Internal Server Error."
                    },
                    "504": {
                        "description": "Gateway Timeout."
                    }
                }
            }
        }
    }
}
 

 

See

How Do I...