Creating your first data parser

A data parser is a Transposit Developer Platform application that relays alerts and related data from external services to Transposit. In Transposit, users can view the output of a data parser and can choose to take action-- for example, creating an activity (incident, service request, etc.).

A data parser is invoked by a request to a webhook URL that Transposit provides.

This tutorial will guide you to building your first data parser in Python.

Creating your first data parser#

  1. Fork sample application: Go to this sample application and click "Fork this app" at the top of the page. Make sure to change the owner to the name of your team, not your personal account.
  2. Deploy: In your application in the Transposit Developer Platform, go to Deploy > Mission Control, change the type to “Data parser” and save. You should use the latest tag for ease of development.
  3. Create a webhook: Go back to Transposit and add a webhook by going to ⚙️ > Webhooks. Click the Add webhook button and select "Custom". Your data parser’s identifier is in the format of maintainer/service_name:tag. If you are following this tutorial, your data parser identifier will be your_organization_name/application_name:latest. Note that if you're adding a Slack channel, the channel must already exist. Click Add.
  4. Call the webhook: You'll notice that an endpoint URL was created for you. Type curl [endpoint_url] in a terminal or go to the URL via your web browser to mimic an external service calling your webhook. You should see an alert in the Activity feed and/or specified Slack channel.

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.

ArgumentTypeDescription
summaryStringA summary of the information presented
descriptionStringA longer description
htmlUrlsArrayAny html URLs used in the message
imageUrlsArrayAny image URLs used in the message
blockKitOverrideObjectSlack block kit blocks to be used to display the message in place of the other fields where applicable

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?#

Now that 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