Data Parser Concepts & Best Practices

A data parser is a defined by a data parser application that relays alerts and related data from external services to Transposit.

To get started creating your own data parsers, see Creating Your First Data Parser.

Once the initial data parser has been created, below are the concept and best practices for developing the parser further.

Data parser response

dataParser.response({display}, standardOutputParams={}, customOutputParams={})

dataParser.response("summary")

The dataParser.response binding creates an event inside Transposit with the invoking webhook information. You can control the look of the event, as well as what information is passed to subsequent actions taken, via the binding's parameters.

Display

The display object contains information used to render the message in different clients. Its properties are optional, but providing at least a summary is strongly recommended.

The block kit in the blockKitOverride field is what is displayed in both Slack and the Transposit UI. If this field is not provided, blocks will be created from the summary and description fields.

At this time, the htmlUrls and imageUrls fields are not rendered anywhere.

Standard output parameters

standardOutputParams is an object whose schema is defined and enforced by Transposit. Currently, it has no defined schema.

Custom output parameters

customOutputParams is a place to store non-changing information to access in subsequent actions. Examples of information you could store include:

• any impacted services
• an instance id attached to the alert
• information related to the team the alert is associated with

You will be able to access this object in any action run connected to the data parser's event.

Here's an example of a full dataParser.response(). Note that we use the block_kit_lib connector to make it easier to form Slack Block Kit.

    response_blocks = api.run(
        "block_kit_lib.markdown_text_section", {
            "text": "Alert: If you want more control over *formatting*, you would use block kit"
    })
    
    display = {"summary": "A webhook was received.",
              "description": "A longer description with some more details",
              "htmlUrls": ["https://myLink"],
              "imageUrls": ["https://someImageLink"],
              "blockKitOverride": response_blocks}
                      
    standardOutputParams = {}
    customOutputParams = {"app_name": app_name,
                      "impacted_service": impacted_service,
                      "instance_id": instance_id,
                      "engineer_oncall": engineer_on_call}

    dataParser.response(display, standardOutputParams, customOutputParams)

If you do not require special formatting, you can provide a string shorthand in place of the display object. Block kit to render in Slack and the Web UI will automatically be created.

    dataParser.response("A webhook was received.", standardOutputParams, customOutputParams)

Where to go from here?

Once you have set up your first custom data parser, you can use the endpoint URL with any external service that supports webhooks to call Transposit.

If you trigger the webhook URL with query parameters or a request body, you will see that data printed into the connected Slack channel. The structure of the data being sent to Transposit with the endpoint URL often depends on the service.

Incoming data

In the sample application, we store different properties such as headers, query_parameters, and parsed_body to retrieve data from the external service to use with Transposit.

    http_event = params["context"]["parameters"]["http_event"]
    query_parameters = http_event.get("query_parameters", {})
    parsed_body = http_event.get("parsed_body", {})

Most informative data will be stored in the query_parameters and parsed_body. Not all external services will contain these properties.

You will find the full incoming HTTP event information in http_event, which includes the method type, header parameters, query parameters, and body parameter:

{
  "http_method": "POST",
  "body": "Hello World",
  "query_parameters": {
    "api_key": "abc123xyz",
    ...
  },
  "headers": {
    "Content-Type": "text/plain",
    ...
  }
}

If the Content-Type is application/xml, application/x-www-form-urlencoded, or text/xml, the event will also include a key called parsed_body, which will contain a JSON representation of the query's body:

{
  "http_method": "POST",
  "body": "key1=value1&key2=value2&key3=value%24",
  "parsed_body": {
    "key1": "value1",
    "key2": "value2",
    "key3": "value&",
  }
  "query_parameters": {
    "api_key": "abc123xyz",
    ...
  },
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded",
    ...
  }
}

Running an operation

In some cases, you might want more data or take action based on a data parser being triggered. Use api.run() to call external services for more data:

    team = query_parameters.get("team")

    try:
        results = api.run("opsgenie.get_oncall_engineer", {
            "team": team
        })
    except ValueError as ex:
        error_message = f"There was an issue getting the oncall engineer:\n{str(ex)}";
        dataParser.response(error_message)
        return