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.
Argument | Type | Description |
---|---|---|
summary | String | A summary of the information presented. Max of 3000 characters. |
description | String | A longer description |
htmlUrls | Array | Any html URLs used in the message |
imageUrls | Array | Any image URLs used in the message |
blockKitOverride | Object | Slack 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?
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