This short tutorial will help you understand how a REST service works. We will see how to define a simple REST service, allowing you to retrieve a file available on the internet and send it as an email attachment.
Tutorial: Recovering a file on the web
Step 1: Create the file recovery operation
1. Creation of the service
Suppose you want to retrieve a file located here: https://www.lerobert.com/sites/default/files/common/CGU.pdf.
- Go to your Design area and click on the “Services” tab.
- First of all you have to create a service of type REST, without authentication, with as “path” the path to your file : “https://www.lerobert.com/sites/default/files/common/”
- To do this, click on Create a new service at the top right of the service configuration page, then select the service type: REST.
- Name your service “Fetch a pdf file, add a description then fill in the field base of the URL with the path to your file: https://www.lerobert.com/sites/default/files/common/
- Authentication type : none
- Click ok, you will be redirected to the service operations configuration window.
2. Creation of associated operations
Once your department has been created, you will assign a set of operations to it.
On the Create Operation window, complete the fields as follows:
- Name your operation “Download TOS”.
- Once your operation is named, click on the tab below Path Setup and fill in the field :
- path HTTP (1) with the end of your URL. In our example it would be “CGU.pdf”.
- The Address field updates and should display the full path to your file: https://www.lerobert.com/sites/default/files/common/CGU.pdf.
To be correct, you would also need to change the value of the Type (MIME) field in the response.
By default, the type application/json is selected, which represents a text data. Since your answer will be a file, you must select the type application/byte-stream, which represents files on the internet. However, your operation will still work if you leave the default value.
If you have filled in the field base of the URL of the service with the full path to your file, you need to leave the field path HTTP empty in your operation.
4. Click Test Operation. An intermediate window informs you of the format in which the form will be displayed. Disregard that for now. Validate this window, you will then see appearing in the result box below, a button allowing you to view and download your file.
5. Your operation is now functional.
6. All you have to do is tell Iterop that you want to put your file in a variable when executing a process using your new operation.
In the Configure Output Data pane at the bottom right of the window, select Type of Transformation: File and click Configure New Variable.
You can increase the size of the right pane of your window by clicking on the button (1)
7. Name your variable my TOS) and click ok.
Step 2: Use this operation in a process
You have now created a REST service. Now you have to call it in one of your processes.
1.Integrate the service into the process design
Suppose you want to send this file by email. You will then need to call up the operation you just created in your process before you send the email. In the design of your process, here is the sequence of the two service tasks you need to design.
2.Configuring the process
- Choose a process and in the configuration of your first task “Retrieving the TOS”, choose the operation you just created. Since your operation has no settings, you don’t have to configure anything else for this task.
- Select the second service task, and choose the mail sending operation. Then open the Service Input Data configuration window.
- You then just have to drag and drop the variable “CGU” 6️⃣ in the attachment part of your mail 7️⃣.
- Configure the rest of your email (recipient, subject, email body…), then validate.
This sub part of the process will then, at runtime, automatically send your file.
To go further
Retrieve another file from the same location as the first one.
The configuration of a service is common to all the operations that are defined for it. So, if you had another file located in the same place as the first one, for example https://www.lerobert.com/sites/default/files/common/monLogo.jpg, you would only have to duplicate your operation, and just change the path HTTP Path to “myLogo.jpg” to have an operation retrieving this other file.
Retrieve a file dynamically
Now suppose you have a collection of files all present at that same location. You are not going to create an operation for each file, but rather in the configuration of your operation let the field Path HTTP editable during the design by activating the switch on the right of the field 1️⃣. This will then add an input variable to your operation.
In your process, you will be able to create a variableFile name that you will drop in the configuration of this operation in the field Path HTTP. The image retrieved by the operation will then be different depending on the value of this variable at process execution.
