Page tree
Skip to end of metadata
Go to start of metadata

The HTTP Request build event handler can be used to call any HTTP endpoint. This can be used to signal other systems when the Continua CI build reaches a certain point or status. You can call any HTTP webhook or endpoint API that suits your needs, such as Slack channel messaging.

The build event handler can be set to automatically respond to any Build Events in the life-cycle of the build. This allows the HTTP endpoint to be hit at any stage of the build process.

Event Handler Name

Friendly name for the event handler (this will be visible in the 'Events' section of the website)

Run Order

The order in which the event handler will be run (relevant in the situation where multiple event handlers are present).

Enabled

Whether this event handler will be run or not. Disabling event handlers can be useful when setting up a build process. 

Type

The type of event handler to be used. Set to HTTP Request to specify a HTTP request for the build event. 

Server URL

The URL of the server that the HTTP endpoint to call exists on. Note that the Continua CI server will require access to the server, as it is responsible for running build event handlers. Please make sure that the server is accessible from the machine your Continua CI server is installed on if experiencing any connectivity issues. 

Resource

The resource endpoint on the server that is to be requested. Note that this is just the pure path to the endpoint, any query strings can be added later in the query string section. 

Method

The method type to use in the request. The available options here are:

  • Get
  • Post
  • Put
  • Patch
  • Delete

The method should match what the endpoint requires so that the correct action or resource is accessed on the server. 

Data Format

The format that the data sent or requested should be presented in. Note that the build event handler will attempt to parse response data in the format selected before extracting any variable values. If this parsing fails, the variable values will not be assigned. 

Also some HTTP endpoints require data to be sent in specific format. If the correct format is not used then the endpoint may fail with a Bad Request response. Make sure the data format is set as required by the endpoint in question. 

The context-type header will also be set based on the data format selected. For example, when selecting JSON, the context-type header will be set to application/json.

Authentication Type

The type of authentication to use to interact with the specified endpoint. The types of authentication possible are:

  • None
  • Basic
  • NTLM
  • Access token as parameter
  • Credentials as parameter

The login method to use will be dependent on the endpoint in question. Some endpoints also offer token-based resource paths to alleviate the need to provide credentials. 

Basic & NTLM Authentication 

Username

The username to use for basic HTTP or NTLM authentication. Note that the username and password are base64 encoded into a basic authentication HTTP header for the request. 

Password

The password to use which matches the username listed above. 

Access Token as Parameter Authentication

Authentication Parameters Type

The type of parameter to send the access key token as. The valid values of Cookie, Form, Header, and QueryString determine where the authentication parameter will be placed in the request sent. 

Access Token Key Name

The name of the parameter for the token. This can differ for each HTTP service implementation. Check with the service in question as to what the expected parameter name is for the key token. 

Access Token

The access token to use for the service. This should match the access level require for the requested service. 

Credentials as Parameters Authentication

Authentication Parameters Type

The type of parameter to send the access key token as. The valid values of Cookie, Form, Header, and QueryString determine where the authentication parameter will be placed in the request sent. 

Username Key Name

The name of the parameter for the username. This can differ for each HTTP service implementation. Check with the service in question as to what the expected parameter name is for the username.

Username

The username of the user accessing the service. This user should have the level of access required to perform the action the HTTP request is asking for. 

Password Key Name

The name of the parameter for the password. This can differ for each HTTP service implementation. Check with the service in question as to what the expected parameter name is for the password. 

Password

The matching password for the user of the service.

 

Request Body

The request body is where the information for the request is placed. In the case above, the request expects a JSON object called payload. The object has two properties called name and icon_emoji - each with values provided for the given request. 

The values can have Continua CI variables included in them so that build information can be passed onto other systems. In the above example the text message passed onto the HTTP request includes the project name and build version number. 

 

Querystring Parameters

These parameters should be provided in <name>=<value> format. Each parameter will be added to the query string which is sent as part of the request. Adding query string parameters here means that you do not have to get the formatting correct for the HTTP query string yourself. All escaping is handled for you when using the querystring parameter entry box. 

POST Parameters

Use this to add any get/post parameters for the request. These are simple parameters that the endpoint may require or use to understand the request being made of it. These parameters should be provided in <name>=<value> format with each pair on a separate line.  

Headers

Allows for adding header parameters for the request. These should be entered in the <name>=<value> format with each pair on a separate line.  

Cookies

Allows for adding cookie parameters for the request. These should be entered in the <name>=<value> format with each pair on a separate line.  

Response Variables

Allows for extracting values from JSON or XML responses and placing them into variables the configuration has access to. To extact values from the JSON and XML responses, JSONpath and XPath can be used. Each has their own syntax for extracting values for nodes within the objects they represent. Below is a list of some of the syntax allowed by each. 

XPathJSONPathDescription
/$The base node in the object.
.@The current object in the node path.
/. or []Accessing a child node, or specific child node
..n/aAccessing the parent of the current node.
//..Recursive child decent.
**Wildcard operator to access any node.
@n/aAccessing an attribute.
[][]Accessing an element within a list of nodes.
|[,]Union of two sets of nodes.
n/a[start:end:step]Accessing elements as a slice of a set of elements.
[]?()Accessing nodes with a filter applied.

Listed below is an example response in JSON and XML.

 

{ 
  "messages": {
    "staging": [ 
      { 
        "author"  : "tim_bot",
        "category": "information",
        "message" : "Building..."
      },
      { 
        "author"  : "tim_bot",
        "category": "information",
        "message" : "Testing..."
      },
      { 
        "author"  : "tim_bot",
        "category": "information",
        "message" : "Completed!"
      }
    ],
    "production": [
      { 
        "author"  : "jill_bot",
        "category": "information",
        "message" : "Building..."
      },
      { 
        "author"  : "jill_bot",
        "category": "error",
        "message" : "Build Failed!"
      }
    ]
  }
}

 

 

<?xml version="1.0" encoding="UTF-8" ?>
<messages>
  <staging>
    <author>tim_bot</author>
    <category>information</category>
    <message>Building...</message>
  </staging>
  <staging>
    <author>tim_bot</author>
    <category>information</category>
    <message>Testing...</message>
  </staging>
  <staging>
    <author>tim_bot</author>
    <category>information</category>
    <message>Completed!</message>
  </staging>
  <production>
    <author>jill_bot</author>
    <category>information</category>
    <message>Building...</message>
  </production>
  <production>
    <author>jill_bot</author>
    <category>error</category>
    <message>Build Failed!</message>
  </production>
</messages>

 

The following are example XPath and JSONPaths that could be used on the above responses to extract information your looking for.

XPathJSONPathResult
/messages/staging/author$.messages.staging[*].authorThe authors of all messages sent to staging
//author$..authorAll the authors of all messages
/messages/*$.messages.*All channels messages were sent to. Staging and production.
/messages//category$.messages..categoryThe categories of all messages.
//staging[3]$..staging[2]The third message sent to staging.
//staging[last()]$..staging[(@.length-1)]
$..staging[-1:]
The last message sent to staging.
//staging[position()<3]$..staging[0,1]
$..staging[:2]
The first two messages sent to staging.
//staging[category="error"]$..staging[?(@.category="error")]All the messages sent to staging with an error category. This would return no values.
//*$..*All nodes in the response.

Successful Response Statues

Check each of the response statuses that would mean the request has been successful. If the request returns a status that is not checked then the build event handler will report an error. If errors are to be treated as failures then the build event handler will fail the build at his point. 

 

When To Run

You can specfy when the build event handler runs by linking it to a Build Event on the When To Run tab

 

Build Event

Select the event which triggers the tag action. You can choose one of the following Build Events:

  • On Build Created
  • On Before Build Queued
  • On Before Build Start
  • On After Build Started
  • On Before Stage Start
  • On Sending Stage To Agent
  • On Stage Completed
  • On Build Pending Promotion
  • On Before Build Continue
  • On After Build Continued
  • On Build Stopping
  • On Build Completed

Stage

For stage events, select the stage this applies to, or "(all stages)" to trigger the tagging action for all stages

Build Status

For "On Stage Completed" and "On Build Completed", you can choose to trigger the tagging action when the build is Successful or has Failed. 

 

Options

Follow redirects

Clear this option to fail if the HTTP endpoint causes a redirection.

Date Format

Optionally specify the date time format used in your request body. If you leave this blank the action will attempt to parse various formats in the invariant culture.

Wait for result

Clear this option to run the tagging action in a separate thread if you don't care about the result eg. whether the action fails or not. 

Ignore errors if existing resource is not found when deleting or updating. Log warning only

An error result will be returned if a Not Found status code is returned when using DELETE or PATCH methods. Tick this option to ignore these errors, only logging a warning to the build log. This is only available if Wait for result is ticked..

Ignore errors if existing response variable nodes are not found. Log warning only

An error result will be returned if a response variable JsonPath or XMLPath expression does not match lease with a matching tag name is not found. Tick this option to ignore these errors, only logging a warning to the build log. This is only available if Wait for result is ticked..

Fail build on error

Tick this to fail the build if the operation returns an error or failure. This is only available if Wait for result is ticked.

 

Log build messages

When this is ticked, Continua CI will add messages to the build log during execution of the HTTP Request build event handler. Build log messages will only be recorded if Wait for Result is ticked.

  • No labels