Generic service with files (binary) & custom HTTP Headers
Compose Enterprise is going through a design update. The illustrations on this page might be of the old design, but the information is up to date. Thank you for your patience during this update!
The Generic Service Builder can extract data from external data sources and make the data accessible through response variables. Documents, images and other files can with the same principles be configured as response variables by using Binary generic services. The contextual meaning of the term Binary refers to files.
In this user guide, we set up a binary generic service and connect the service to a workflow. However, we’ll start with a walk-through of custom HTTP request headers. Knowledge about request headers is a prerequisite to enable secure data and file operations in generic services.
Custom Request Headers (HTTP Headers)
Compose allows you to generate custom request headers (HTTP headers) in your generic services. When a service call is run the HTTP request with the custom request headers will be sent to the server, and we get a response. Every new generic service has the following default headers:
The default request headers may be edited or removed, and custom headers can be added in the Generic Service Builder. Create a Generic Service by selecting the New Generic Service button in the Organizer top menu and enter the preferred name. We intend to demonstrate how to get a photo from a URL with this service, ergo the name Get Photo.
Double-click the new element to open it in the Generic Service Builder. Navigate to the Request Headers section, and you’ll see the aforementioned default headers.
The default headers may be edited or removed, and custom headers can be added by clicking the Create button.
A new line will appear and you can enter a name and a value for the header. Header names (keys) and values must conform to their respective parts in the HTTP standard. The value can be either static or connected to a request variable. The first new header Content-Type – application/json is static, and is the standard header for allowing processing of JSON data. JSON data, along with XML, is one of the most used data formats in data models accessible through APIs.
In the second header Authorization header – {key} we demonstrate how you reference a request variable in a header. With {}-notation (curly brackets) you can use a request variable as a header value.
We have created the header, but we have not yet added the request variable, so head to the Settings section, and click the Create button in the Request Variables panel.
Then enter the value we entered for the request header (in our case key).
With this request variable, you can use any variable from the workflow to populate the value in the header. User case: If the header value needed is an access token, then you usually create a separate generic service generating the token as a response variable. Then you connect that response variable to the request variable of this generic service to populate the access token in the header.
Note: If you are following this example and want to create a binary generic service, then remove the last header. The binary generic service will retrieve a photo without needing authorization, and the last header will fail the service call.
Generic Service for a binary response variable
In this example the response will be an image, and we will therefore select Binary format for the Response Variable. (Notice how the Response section is disabled when you select Binary, as you don’t need any XPath expressions to get files.)
Enter a Variable Name and a File Name for the binary response (in this example photo and Norway.jpg). When the response variable properties have been set, please check that the Method is set to GET.
Enter the source URL for the image. In this case we want to use a URL with a variable, so we can access a full library of images by changing the suffix (the request variable key) of the URL: https://www.usecompose.com/wp-content/uploads/{key}.
The settings for this example service are now completed. To be able to use the generic service in a workflow, remember to Save Draft and create a New version.
Connect binary services to workflows
In this short example we will show how to use the generic service with custom request headers created above in a workflow. The procedure of connecting generic services to a workflow is extensively covered in the user guide Generic services (form and workflow population). Therefore this guide will mainly touch on the specific nature of binary services. We will also not go in detail on standard configurations, so if you’re brand new to creating workflows, we highly advised visiting the Build a simple workflow user guide for an overall introduction.
We will connect the service to a Generic Service activity and send the response photo as an attachment in an email. Create a workflow with activities in this chronological order – a Start Point, a Generic Service activity, a Send Email activity and an End Point. Start by selecting the Generic Service activity and connecting it to our binary service by clicking Browse.
You’ll see the name and version of the selected generic service in the Properties panel. We need to map the request variable to a value, so press the Map Request Variables button.
Request variables can be mapped to a static value or a value from the workflow. In this example we will map the variable to a static value, as there are no previous workflow activities with fitting URL variables. The value in our case, 2019/08/Om-Compose.jpg, illustrates which photo in the library we aim to retrieve. Click OK.
Select the Send Email activity, and configure the General and Content tab of your choosing. Note: The domain of the sender email address must either be the usecompose domain, or a domain permitted by Compose to distribute emails on behalf of, usually domains of customers renting Compose. noreply@usecompose.com is a good back-up sender address.
Navigate to the Attachments tab to attach the photo to the email. Click Add Attachment.
Browse to find the attachment, click the arrowhead of the generic service activity to reveal the photo response variable.
Finish in the menu and the photo will appear as an attachment in the attachments table.
Configure the other workflow activities as you wish, Save Draft, Create a version and press Play to start the workflow. You will now be able to run the workflow and the custom request headers will be included in the service call.
The example workflow is attached. Note: This workflow does not have any respondent user interface activities, hence in respondent view the workflow will go straight to the end point. Therefore you must remember to change the To Email to your own email address to get the attachment!
