¶ Configuring Links
Links are a way to connect tasks. By connecting tasks you can construct the flow in the workflow. Besides connecting tasks you can also pass parameters from the result of one task to the next task in the workflow. This is of particular importance when connecting API tasks. API tasks are tasks that call an API as their main function. They are colored blue in the Studio.
You can create a link by using the "Add Link" button in the central panel of the Studio. Note that you must have first created a product, a workflow and at least two tasks to connect. You must provide the source task, the target task and the link type. This will effectively connect the two tasks and a link will appear in the workflow graphical representation.
¶ Passing parameters to the next task
The Link view interface allows owners and designers to update links, manage parameters, and configure link types between tasks in a workflow. Start by clicking on the link on the workflow graph.
¶ Updating a Link
To update a link's properties:
- Ensure that you have selected a link within a workflow.
- Use the 'Update' button to save changes made to the link.
¶ Managing Link Parameters
Link parameters define the data that is passed between API tasks (colored blue). These include:
- Resource and Path Parameters: These parameters are part of the URL path of the API call.
- Query Parameters: These parameters are appended to the URL of the API call.
- Request Body Parameters: These parameters are included in the body of a POST request.
To edit any of these parameters, use the corresponding JSON editor provided in the interface. If Pass following Parameters to target API is checked the Studio will pass the parameters defined in the link to the next API task.
Whenever {{property name}} is used in one of the parameter fields, as shown in the examples below, the Studio will search for the value associated with the property name in the response body of the API that serves as the source API task for the link. It will replace {{property name}} with the corresponding value from the response. Refer to the examples below for further clarification.
¶ Resource and Path Parameters
In the context of API design, Resource Parameters refer to the static parts of an API URL that define the type or collection of resources, whereas Path Parameters refer to the variable parts of the API URL that specify particular instances of those resources. In the Studio environment, both are combined into a single object called "Resource and Path Parameters". The order in which these parameters are presented is dictated by the "Path Order" field.
¶ Example
Given a GWOCU studio JSON formatted input for Resource and Path Parameters:
{
"userResource": "users",
"userId": "{{userId}}", // Note the Studio will search for the value of this property in the response body of the executed source task.
"languageResource": "language",
"languageId": "Dutch"
}And a Path Order input of:
["userResource", "userId", "languageResource", "languageId"]And a Result Body of a previously executed API:
{
result: {
"userId": "1234"
}
}Note: the previously executed API must be the source task of the link that is under consideration. The source task must have an API that is associated with it and it must have been previously executed in the cURL view of the task or the workflow execution view.
With a base URL of:
https://example.comThe constructed URL for a GET API request would be:
GET https://example.com/users/1234/language/Dutch¶ Task Affected
Note that the task that will be affected by setting these parameters is the task to where the link is pointing, but only if it is an API task (colored blue). The Base URL for this API can be set in the API Manager page within the Studio. You can find this API there and change the "Base URL" value if needed. If there are other links pointing to the same task and they are allowed to pass parameters then the Resource and Path Parameters will be combined. To see the end result of the URL go to the cURL view of the task and take a look at the URL.
¶ Query Parameters
Query Parameters are a way to pass additional information to an API endpoint. They are appended to the end of the URL after a ? and are used to filter, sort, or specify additional options for the request. Each parameter is a key-value pair, and multiple parameters are separated by an &.
Query parameters are commonly used in GET requests to refine the data that is being requested from the server.
¶ Example with Query Parameters
Using the previously constructed URL example for Resource and Path Parameters, let's expand it to include query parameters.
Base URL with Resource and Path Parameters:
https://example.com/users/1234/language/DutchNow, suppose we want to add query parameter to filter results by date and sort them by name. The query parameters might look like this in the Studio:
{
"date": "2024-05-27",
"sort": "name"
}This will result in a generated query parameter string like:
?date=2024-05-27&sort=nameAnd the complete URL with Query Parameters would be:
GET https://example.com/users/1234/language/Dutch?date=2024-05-27&sort=name¶ Task Affected
Note that the task that will be affected by setting these parameters is the task to where the link is pointing, but only if it is an API task (colored blue). If there are other links pointing to the task and they are allowed to pass parameters then the query parameters will be combined. To see the end result of the URL go to the cURL view of the task and take a look at the URL.
Again, you may choose to use a property value of a previously executed API in the workflow by using "{{property name}}" in the query parameter object. For instance:
{
"date": "2024-05-27",
"sort": "{{name}}"
}¶ Request Body Parameters
Request Body Parameters are used to send data to the server in the body of the HTTP request. This is common with POST, PUT, and PATCH requests. The data is typically sent in JSON format.
Request Body Parameters are used when you need to send more complex data structures to the server.
¶ Example with Request Body Parameters
Continuing with the context of our previous examples, let's consider creating a new user language preference using a POST request.
Base URL:
https://example.com/users/1234/languageSuppose we want to add a new language preference for the user with ID 1234. The request body might look like this:
{
"language": "Dutch",
"level": "Intermediate"
}Complete Request with Request Body
POST https://example.com/users/1234/language HTTP/1.1
Host: example.com
Content-Type: application/json
{
"language": "Dutch",
"level": "Intermediate"
}You may choose to use a property value of a previously executed API in the workflow by using "{{property name}}" in the Request Body Parameter object.
¶ Task Affected
Note that the task that will be affected by setting these parameters is the task to where the link is pointing, but only if it is an API task (colored blue). The Base URL for this API can be set in the API Manager page within the Studio. You can find this API there and change the Base Url value if needed. If there are other links pointing to the task and they are allowed to pass parameters then the Request Body Parameters will be combined. To see the end result of the URL go to the cURL view of the task and take a look at the URL.
¶ Link Type Configuration
The type of link can be selected from the options provided, which affect the visual representation of the link in the workflow graph:
- Straight
- Smooth Curve
- Full Curve
¶ Changing Source and Target Tasks
If you need to change the source and target tasks of a link, you must delete the current link and create a new one. Use the 'Remove Link' and 'Add Link' buttons located in the central panel to perform these actions.
¶ General Usage Tips
- Changes in the interface will not be saved until the 'Update' button is clicked.
- Ensure all JSON fields are valid before attempting to save changes.
- Use the source and target fields to understand the direction and endpoints of the link.
¶ Important Considerations
Always ensure that changes made are necessary and accurate, as modifying link parameters and types can significantly impact the behavior of the workflow.