Creating an HTTP Poke or Get External Data Handler

The HTTP Poke and Get External Data handlers enable MEP to reference data in an URL in order to send that data to an external platform, while the Get External Data handler enables MEP to reference data in an URL in order to send that data to an external platform. To create the HTTP Poke or Get External Data handler, you must first create the handler. Once the handler is created you can then define the header and body to further customize the request. EL expressions are also supported for these two handlers. See EL Support for the HTTP Poke and Get External Data Handlers.

Note: Examples shown on this page use the HTTP Poke handler. However, the steps and information are the same for the Get External Data handler.

Handler parameters

Supported HTTP Poke methods are:

• GET: Used to retrieve information from an external platform.
• PUT: Used to update data in the previously selected URL using a previously defined Header and Body in order to send the request to an external platform.
• POST: Used to insert data in a previously selected URL. When POST is passed in the request, the user must specify the headers and the body in order to send the complete request to an external platform.
• DELETE: Used to eliminate data by sending a request to an external platform.

Supported header fields

Headers can further be refined by adding the following supported header fields or Custom Headers to your handler:

• Accept: Indicates which content types are supported. For example, this might be text/xml or image/*.
• Accept-Charset: Indicates which character sets are accepted in the response. For example, this might be utf-8.
• Accept-Encoding: Indicates which types of content encoding are supported. For example, this might be gzip.
• Accept-Language: Indicates which language is supported using a two- or three-character string. For example, this might be en-US or es. Use an asterisk (*) as a wildcard.
• Accept-Datetime: Indicates that the request wants access to the past state of a previous request.
• Authorization: Allows credentials to be passed to authenticate a user agent with the origin server, typically after a 401 (Unauthorized) response is received. For example, this might be Basic. Authorization can also be set in the Advanced section. Any authorization you set there will overwrite any authorization you pass in this Headers section.
• Cache-Control: Indicates that the request is specifying a rule for caching requests and responses. For example, you might specify no-cache, public, private, etc.
• Connection: Controls whether or not the connection stays open after the transaction completes. This can be close or keep-alive.
• Cookie: The request header contains previously sent stored HTTP cookies.
• Content-Length: Sets the length of the content body, in octets, if the message header does not contain a Transfer-Encoding field.
• Content-Type: The MIME body type for POST and PUT requests. For example, this might be text/html. You can customize the header by including one or more of these supported Content-Types:
  • text/html
  • text/plain
  • text/css
  • text/csv
  • text/calendar
  • application/json
  • application/xml
  • application/rtf
  • application/xhtml+xml

  In addition to passing the Content-Type, you can also define the character set for that content type. For example, in the header you can add Content-Type: application/json; charset=UTF-8, separating the content type and character set with a ";" (semi-colon).

  Note: If you define the character set with the Content-Type, and then select a different type from the Encode Using drop-down list in the Header section, the value selected from the Encode Using drop-down list will overwrite any value defined in the header. For example, if you define charset=utf-8 in the header, and then select ISO-8859 (Latin-1) from the drop-down list, ISO-8859 (Latin-1) will be the encoding for Content-Type: application/json.

You can pass any combination of header field you want, adding each header field to a new row, with no punctuation separating the rows. For example, you could create a header similar to this:

Content-Type: application/json; charset=UTF-8
Accept-Language: EN
Cache-Control: only-if-cached
Connection: keep alive
Content-Length: 102 

Custom Headers

In addition to the HTTP Header definitions above, the handler supports custom headers as name/value pairs that you might want to pass within the header. Examples of these might include X-Powered-By: PHP/5.2.6-2ubuntu4.2, X-Pingback: example.org/xmlrpc.php, or X-Forwarded-For: 192.168.123.10. Custom headers should be formatted as header name: value, with each name/value pair on its own line in the Headers section:

Custom ID for Headers

A unique Id is defined for the handler request as part of the header X-Request-Id. This ID is defined internally by MEP for the handler. It is persistent and cannot be modified. If you try to pass X-Request-ID in the header field, an error is returned.

Expression Language in Headers

You can define a Header value using MEP Expression Language (EL). See EL Support for the HTTP Poke and Get External Data Handlers for details.

Body

Body text is any message that follows the header. PUT and POST require Body text, but it is not required for the GET and DELETE methods. The Content-Type determines the Body format. The following show JSON and XML examples.

JSON Body example

{
"version": 1,
"code": "CMX2",
"name": "CMX2 Example",
"createdAt": "2017-12-26 17:24:02",
}

XML Body example

<?xml version="1.0"?>
<catalog>
	<id="example1">
		<code>CMX2</code>
		<name>CMX2 Example</name>
		<createdAt>2017-12-26 17:24:02</createdAt>
	</id>
</catalog> 

HTTP Poke and Get External Data Handler Security

In the request body you can one of two authorization methods: HTTP Authorization or HTTP Proxy Authorization. Any security you set from within the body will overwrite any security you might have passed in the header. You can pass a User name and Password.

• HTTP Authorization: This method contains the credentials to authenticate a user agent with a server.
• HTTP Proxy Authorization: This method contains the credentials for authenticating a user agent to a proxy server.

Options for both Authorization types are :

• NONE: This is the default value. No security is enabled. If None is selected, you can add authorization credentials to the Headers field without overwriting them.

• BASIC: Enables basic authentication. You will be prompted to replace the example User name and Password with those of the user requesting authorization. Validation is performed on the credentials passed here. If the credentials are entered incorrectly, or if you do not replace the example text with actual credentials, authorization will fail.

  

  Note: The Password field cannot be NULL. If the field is empty when you save the handler, the latest password value entered at that moment will be saved.

• CUSTOM: Enables you to pass custom for the authorization. Use this authorization type when you want to define any authorization other than Basic. When you select this Authorization type, you will be prompted to supply the custom credentials:

  

Important: A User name can be no longer than 255 characters and cannot begin with ${; a Password can be no longer than 32 characters. You can use a valid EL for a User name.

Error messages

Validation is performed on the fields and formatting of information you enter. If the handler finds an error in either the Header or Body, an error message displays. You cannot save your changes until the error has been fixed. Here are just a few examples:

HTTP Poke and Get External Data handler examples

The following show example HTTP Post and Get External Data handlers.

Note: For the steps to create a service, see Creating a Service.

HTTP Poke handler using POST with JSON

This example shows an HTTP Post handler with the Body formatted using JSON.

HTTP Poke handler using POST with XML

This example shows an HTTP Post handler with the Body formatted using XML.

HTTP Poke handler using POST and a different character encoding

This diagram shows an HTTP Poke service created in which the character encoding is defined as UTF-8 in the header. However, ISO-8859 (Latin-1) is selected from the Encode Using drop-down list. ISO-8859 (Latin-1) will overwrite the character encoding defined in the header.

HTTP Poke handler using PUT

This diagram shows an HTTP Poke service created in which the network code is updated and passed in the URL, while the code and name are passed in the Body.

HTTP Poke handler with Basic Authorization

This diagram shows an HTTP Poke handler where the Security Authorization is Basic.

HTTP Poke handler with a Custom Security Proxy-Authorization

This diagram shows an HTTP Poke handler where the Security Proxy Authorization is Custom.