Start event trigger

Library tth-api-client is the recommended tool for the interaction with the API, including starting an event trigger. Using this tool is the common and suggested way to start event trigger from external sources.

from tth.client import APIKeyClient
                
                
hub_address = "https://tth-address.cloud"
api_key_value = "apiKeyValue"
trigger_id = 1
trigger_parameters = {"parameter_name": "parameter_value"}
                
# create API Key client
client = APIKeyClient(hub_address, api_key_value)
                
# start event trigger
execution_id = client.trigger.start(trigger_id, trigger_parameters)
                
# obtain details of started execution
execution_info = client.execution.get_info(execution_id)
print(execution_info)
                
# obtain execution status
execution_status = client.execution.get_status(execution_id)
print(execution_status)
                
# wait for execution to finish
execution_status = client.execution.wait_until_finished(execution_id)
print(execution_status)
            

Alternatively, an event trigger can be started by manually sending an HTTP request to the API.

import requests

        
auth_token = 123456 # Replace with the token value of the trigger you want to start
tth_url = "URL" # Replace URL with the URL of your TTH 
 trigger_id = 4  # Replace with the Trigger Number you would like to start
branch = "main"
                
trigger_url = f"{tth_url}/api/triggers/start/{trigger_id}"
exec_id = requests.post(trigger_url, headers={'X-API-Key': auth_token}).json()
exec_url = f"{tth_url}/api/executions/status/{exec_id}"
                
while True:
     exec_status = requests.get(exec_url,
     headers={'X-API-Key': auth_token},
     json={"parameters": [{"name": "BRANCH", "value": branch}]}).json()['status']
     if exec_status not in ['QUEUED', 'RUNNING']
         break
                
     if exec_status != 'PASSED':
         raise Exception("HIL Job did not pass!")                  

When creating a webhook, make sure to:

• Insert proper URL that corresponds to the URL of the event trigger that you would like to be started from the webhook
• Insert API key value as the secret token
• Check if data is sent in JSON format

Since webhooks usually do not allow defining custom request body, you can pass the trigger's parameters' values via query variables inside the URL. In order to achieve that, format URL as

https://test.typhoon-hil.cloud/api/triggers/start/5?first_param=first_value&second_param=second_value

where you can define as much parameters as your job or pipeline has.

If you want to use some of the data that are in webhook request payload defined by the platform that sends request, you need to rename a parameter of the job or pipeline that the event trigger refers to so that the name of the parameter is the same as a property name inside the webhook request payload. For example, if you take a look at the payload of the request that is sent when push event occurs inside the GitHub documentation, you can see it provides several properties among which is ref property that refers to the branch name to which new code was pushed. If you wanted to pass this value as the branch value of the Clone repository job step, job would need to have parameter called ref, and for the branch parameter you could pass the value by inserting $ref. In case that desired property of the payload is nested and is not in the first level of the JSON payload, you can use it by the name that you can obtain by concatenating its path from the root of the payload with underscores. For example, you want to use property description inside the following JSON payload

{
    "ref": "ref/heads/develop",
    "repository: {
        "url": "https://test.gitlab.com/my/repository",
        "description": "repository description"
    }
}
                

you would need to have a job or pipeline parameter with name repository_description and use it as the variable $repository_description inside the job or pipeline configuration.