Connector Builder Guide – PreRequest and PostRequest Hooks
Open Connectors consists of over 170 connectors to 3rd Party Applications natively embedded in the SAP ecosystem. If the Connector you need does not exist in the catalog, you can build it quickly with Connector Builder. This instruction guide will walk you through using this tool, with concrete examples throughout. The beginning, Part 1, can be found here.
Hooks act as request "middleware" and can be used to programmatically manipulate requests made to the connector. Hooks applied on the Setup screen of Connector Builder will be applied to every request (globally). If you'd only like to manipulate certain requests, add a prerequest hook on a specific resource on the Resources screen.
Hooks are written in Javascript. You will notice that after executing a resource, the data that is available to the prehook is populated in the right hand side. Let’s go through each of these available variables with an example.
Img 1 - The Pre Hook after Resource Execution
Img 2 - Creating a Pre Hook (+)
Let’s go through all the different available variables:
request_method (string): The HTTP method of the API call that is exposed to the user in the API docs. Ex: “get”
request_vendor_method (string): The HTTP method of the API that is actually sent to the vendor. For normalization purposes, the method shown to the user might make more sense conceptually to be “GET” but the actual method might be “POST.”
request_headers (object): If you want to access a supplied header and change it:
request_vendor_headers (object): The actual headers sent to the vendor: Ex: If you want to add a header key, like “Authorization”, having a value that is stored in the configuration:
request_path (string): The path exposed to the user:
If on the Resources tab of Connector Builder, a GET /subscription resource is created, the left one is part of the request path, which the actual output being: /hubs/general/subscription
request_vendor_path (string): The path that will be sent to the provider. If the path starts with https, it will be used as the request URL and will not be concatenated to the Base URL found in the Setup screen of Connector Builder. Here is an example of manipulating a path before being sent to the provider. It assumes an id parameter was sent by the user.
request_path_variables (object): The variables in the request path and their values. If the request_path was /subscriptions/{id}:
The output of console.log(request_path_variables) would result in:
{
"id": "4"
}
If this was run after the user populated “4” in the Id field.
request_parameters (object): The query parameters sent as part of the API calls in the request.
When you create a resource on the Resources screen of Connector Builder, the GET resources will automatically populate some query parameters - such as page and pageSize. Let’s add a query parameter and call it fileId:
Now let’s access this query parameter in the prehook:
request_vendor_parameters (object): The actual query parameters sent to the vendor. If we wanted to take fileId from above and add add it to an array, we could do that and then send it to the vendor. Some vendor APIs have very nuanced requirements and it is best to abstract these out to keep the exposed API as normalized as much as possible:
request_body (string): The body sent with the request by the user.
request_vendor_body (can accept list, object, string on write): The body sent to the vendor.
If you have created a POST resource on the Resource screen of Connector Builder to take in a body, it can be altered before sending it to the vendor. In this example, we will put the body in an array to comply with how the vendor needs to receive it:
request_body_map (object) - The request body sent with the API call - but represented as an object
request_vendor_body_map (object) - The request body send to the vendor - specifically represents an object
request_vendor_url (string) - The fully formed endpoint request URL that will be used to call the vendor endpoint. This is like request_vendor_path if request_vendor_path started with https.
request_expression: (list of objects) The CEQL where parameter of the resource which has been converted to a list of maps containing "value, operator, & attribute". This can be used to build a vendor query. Ex: firstName = 'John' is represented as [{attribute: 'firstName', value: 'John', operator: '='}]
request_previous_response: (object or list) The response of the previous chained resource. If this resource is not part of a chain this value will be null. Represented as a map or list.
request_previous_response_headers: (object). Works like request_previous_response
request_root_key: The path build a sub-object in the request JSON payload, specified in dot notation, (e.g. data.record). Set this to send a flattened object in a nested format, (e.g. data.record for { foo: 'bar'} becomes { "data": { "record": { "foo": "bar"}}})
configuration: (object) Configuration properties that are part of the instance. Represented as a map.
PostRequest Hooks
Post Hooks work the same as Pre Hooks, but in addition to the Pre Hook data, the response data is also available to help sculpt the final response.
Let’s run GET /contacts and see what values the various variables contain. Keep in mind, that we have a response root key “data” in place, however, the response_body represents the raw response body.
response_body (map)
response_body_raw (string)
response_body_raw_map (object)
response_headers (object)
response_root_key (string)
response_status_code (number)
Open Connectors consists of over 170 connectors to 3rd Party Applications natively embedded in the SAP ecosystem. If the Connector you need does not exist in the catalog, you can build it quickly with Connector Builder. This instruction guide will walk you through using this tool, with concrete examples throughout. The beginning, Part 1, can be found here.
Hooks act as request "middleware" and can be used to programmatically manipulate requests made to the connector. Hooks applied on the Setup screen of Connector Builder will be applied to every request (globally). If you'd only like to manipulate certain requests, add a prerequest hook on a specific resource on the Resources screen.
Hooks are written in Javascript. You will notice that after executing a resource, the data that is available to the prehook is populated in the right hand side. Let’s go through each of these available variables with an example.
Img 1 - The Pre Hook after Resource Execution
Img 2 - Creating a Pre Hook (+)
Let’s go through all the different available variables:
request_method (string): The HTTP method of the API call that is exposed to the user in the API docs. Ex: “get”
request_vendor_method (string): The HTTP method of the API that is actually sent to the vendor. For normalization purposes, the method shown to the user might make more sense conceptually to be “GET” but the actual method might be “POST.”
request_headers (object): If you want to access a supplied header and change it:
request_vendor_headers (object): The actual headers sent to the vendor: Ex: If you want to add a header key, like “Authorization”, having a value that is stored in the configuration:
request_path (string): The path exposed to the user:
If on the Resources tab of Connector Builder, a GET /subscription resource is created, the left one is part of the request path, which the actual output being: /hubs/general/subscription
request_vendor_path (string): The path that will be sent to the provider. If the path starts with https, it will be used as the request URL and will not be concatenated to the Base URL found in the Setup screen of Connector Builder. Here is an example of manipulating a path before being sent to the provider. It assumes an id parameter was sent by the user.
request_path_variables (object): The variables in the request path and their values. If the request_path was /subscriptions/{id}:
The output of console.log(request_path_variables) would result in:
{
"id": "4"
}
If this was run after the user populated “4” in the Id field.
request_parameters (object): The query parameters sent as part of the API calls in the request.
When you create a resource on the Resources screen of Connector Builder, the GET resources will automatically populate some query parameters - such as page and pageSize. Let’s add a query parameter and call it fileId:
Now let’s access this query parameter in the prehook:
request_vendor_parameters (object): The actual query parameters sent to the vendor. If we wanted to take fileId from above and add add it to an array, we could do that and then send it to the vendor. Some vendor APIs have very nuanced requirements and it is best to abstract these out to keep the exposed API as normalized as much as possible:
request_body (string): The body sent with the request by the user.
request_vendor_body (can accept list, object, string on write): The body sent to the vendor.
If you have created a POST resource on the Resource screen of Connector Builder to take in a body, it can be altered before sending it to the vendor. In this example, we will put the body in an array to comply with how the vendor needs to receive it:
request_body_map (object) - The request body sent with the API call - but represented as an object
request_vendor_body_map (object) - The request body send to the vendor - specifically represents an object
request_vendor_url (string) - The fully formed endpoint request URL that will be used to call the vendor endpoint. This is like request_vendor_path if request_vendor_path started with https.
request_expression: (list of objects) The CEQL where parameter of the resource which has been converted to a list of maps containing "value, operator, & attribute". This can be used to build a vendor query. Ex: firstName = 'John' is represented as [{attribute: 'firstName', value: 'John', operator: '='}]
request_previous_response: (object or list) The response of the previous chained resource. If this resource is not part of a chain this value will be null. Represented as a map or list.
request_previous_response_headers: (object). Works like request_previous_response
request_root_key: The path build a sub-object in the request JSON payload, specified in dot notation, (e.g. data.record). Set this to send a flattened object in a nested format, (e.g. data.record for { foo: 'bar'} becomes { "data": { "record": { "foo": "bar"}}})
configuration: (object) Configuration properties that are part of the instance. Represented as a map.
PostRequest Hooks
Post Hooks work the same as Pre Hooks, but in addition to the Pre Hook data, the response data is also available to help sculpt the final response.
Let’s run GET /contacts and see what values the various variables contain. Keep in mind, that we have a response root key “data” in place, however, the response_body represents the raw response body.
response_body (map)
response_body_raw (string)
response_body_raw_map (object)
response_headers (object)
response_root_key (string)
response_status_code (number)
- SAP Managed Tags:
