Sortable is a JavaScript library for reorderable drag-and-drop lists.

Where to place the component

After having it installed on your environment you have to add its dependencies to the module where you wish to make use of the component, like this:

The next step is to drag and drop the Webblock SortableJSList into the screen in the position you’ll put your list.
This Webblock has a placeholder, inside of which you should place the list to which you intend to add the sorting behavior. This list can be inside of another element, like a container, it doesn’t need to be the direct child inside of the placeholder, however, for readability purposes, you should avoid wrapping the list with too many elements.

Besides the placeholder, this block has three inputs, namely:

• ListWrapperQuerySelector
• ListName
• OptionsJSON

Let’s look at each one separately.

Inputs

ListWrapperQuerySelector:

This is a mandatory input, and it should take in a CSS selector string referencing the direct parent of the items you wish to add the drag and drop behaviour to.

<table id=“tableid”>
  <thead>
    <tr>
      <th>Month</th>
      <th>Savings</th>
    </tr>
  </thead>
  <tbody> <!—- this is the parent -->
    <tr> <!— this is a children —>
      <td>January</td>
      <td>$100</td>
    </tr>
    <tr>
      <td>February</td>
      <td>$80</td>
    </tr>
  </tbody>
  <tfoot>
    <tr>
      <td>Sum</td>
      <td>$180</td>
    </tr>
  </tfoot>
</table>

Looking at the example table above, if you wanted the lines of a table to be draggable, one option would be to use “#tableid tbody” since the rows are direct children of the tbody. Some other examples would be just “tbody” or “table tbody”, however, these have the disadvantage of not using the unique ID of the table, so they could lead to some strange behaviors if you have more than one table inside of the SortableJS placeholder.

In our app, we decided to use: “#” + Left_table.Id + “ tbody”

Similarly, if using a List, you could do something like “.list.list-group” or, using id’s again, “#” + List.Id.

ListName:

This input is also mandatory and is used to identify the list or lists that were edited in the onDragEnd event. This event is discussed later in this post.

Please note that to have a basic usage of this component, these two inputs are all you need.

OptionsJSON:

This input is not mandatory, since it has a default value. This one will allow you to customize the behavior of your draggable list. The format of the input is a JSON string and you can find all the possible parameters here, however, we’ll explore a few of them below.

{
    group: {
        name: 'list_group'
    },
    sort: true,
    handle: '.list-handler'
}

From the example above , the first parameter is the “group -> name”, which is used to group lists, allowing its items to be dragged from one to the other. In order for the items in one list to be dropped into another, they must belong to the same group. You can further customize the conditions in which this is allowed, by following this documentation.

Then, we see the “sort” parameter. This one is simply to enable the sorting on this list, so, most of the time, you want to have it set to true.

Finally, the last one is the “handle”, which allows you to set a handle for your draggable element. This means that, when a handle is set up, to be able to drag an element, the user has to do so by dragging on that predefined handle. The value that this parameter accepts is a CSS selector string as well.

OutSystems Variables

So far we have been able to make the elements on a list or table draggable. However, all that does is affect the look of the webpage on the client’s browser, without any impact on the variables in OutSystems.

To be able to reflect the changes made by the user in your OutSystems variables, you have to code a bit and create some logic. There are a lot of different alternatives to this process, which would be too extensive to explore in one post. For example, one idea would be to read the order of the elements on the screen using JavaScript, only when the user stops moving things around and saves. This way you could store the sorted order of ids or add a parameter on the Database representing the “Order”, which would take the index of each item on the sorted list.
Another method is to store the changes as they happen, making use of the event OnDragEnd triggered by the SortableJS block.

OnDragEnd event

This event has one structure as its output, called OnDragEndElement, which is composed of four parameters that give you information about the element that was dragged by the user:

• OldIndex — (Zero Indexed) The index of the element in the original list from which it was dragged from;
• NewIndex — (Zero Indexed) The index of the element in the list to which it has been dragged to.
• From — The original list group name where the element was dragged from;
• To — The list group name where the element was dragged to;

Using this event, we can create a Handler action that will manipulate the OutSystems List to reflect what has been performed by the client on the DOM.

One example of such an action could be as follows:

Here we start by locally storing a copy of the dragged element in the variable, SelectedElement. Then, we remove this element from its list, by referencing it by the OldIndex. Finally, we insert the copied element back into the list in its new index.

Please note that this example does not take into account the possibility of dragging and dropping elements between different lists. To achieve that, you’d have to add some logic to look at the parameters “From” and “To” of this event. That use case will not be covered in this post, but please reach out to us if you need help with that.

Conclusion

As you can see this is a component with almost infinite use cases, input combinations, and also a lot of different ways to interact with it depending on your necessities and Data Model. However, despite all of this customizability, the basic usage of the component is quite simple, since you only have to set the ListWrapperQuerySelector and the ListName.

Please, share with us your usage of this component and any ideas for further development.

TLDR: You can also check this content on YouTube: https://youtu.be/2Mdkz_FZLsQ

Lots of teams have their data layer exposed through GraphQL.

Unfortunately, OutSystems doesn’t natively support this query language, but that’s no reason to worry! Since a GraphQL request is, at its core, just a more complex POST call, we can definitely integrate with it in OutSystems by:

• Building a .Net integration with Integration Studio
• Consuming a REST call in Service Studio

In this article, we will focus only on the latter. If you’re curious, you can check our live demo here.

Basics of GraphQL

GraphQL provides a standardized and flexible way to structure queries and exchange data among various database and server platforms.

When you perform a GraphQL call, you have three main areas:

• The Query or Mutation, where you define what you want to get or update;
• The Variables, like search filters or data to be inserted into the database;
• The Response, like the result of your query or error messages and codes.

Below, we’ll look at each of these three areas and present some syntax fundamentals like doing a query with arguments. To do so, we’ll consume a GraphQL endpoint to retrieve country information, exposed at https://countries.trevorblades.com.

Query:

In line 1, we have the keyword “query”, indicating that we intend to retrieve some data. If our goal were to change or insert data in the database, we would use the keyword “mutation” instead.

Moving forward, you have to pick a name for your query. We selected “GetCountryByName”. Then, since this query is for a specific country, we have the input variable $countryCode: ID!. Variables are prepended with a dollar sign, and you must give them a name and specify their type. In this case, the variable is called “countryCode” and is of type ID, which is defined in the schema of the GraphQL endpoint. Pay attention to the exclamation mark in ID!. This means that this is a non-nullable input, so you cannot leave it blank or ignore it when you perform the query. In other words, this field is mandatory.

Looking now at the second line of the query, we see that we are calling a query already defined in the documentation of the GraphQL endpoint.

This query is called “country” and receives an input called “code” of type “ID!”. In our use case, we’ll pass in our variable “$countryCode”.

You might be wondering, if the “country” query already exists, why are we creating a query of our own to call it? There are at least a couple of reasons. First, we want the input “code” to be dynamic, so we need to define a variable to send into the query. If we only wanted the values for one country, e.g. “BE”, we could call the “country” query like this:

Then, the second reason to create a query of our own is related to the Response we want to get. One of the great things about GraphQL is that you can tailor the Response to have the information you need in the exact structure that you need it in. Because of this, whenever you create a query, you must specify what you are querying in the same structure in which you want the Response to be. This leads to the possibility of having two queries for the same data but with different response structures, meaning that you can have the same fields in a different order or other fields altogether. You can find this structure in the remaining lines of the example query.

Variables:

Sometimes, when we perform a GraphQL query, we need to pass in some inputs, like search filters, or, when performing a mutation, we need to pass the data that needs to be stored in the database. This is done through the variables section.

In the case of our example, this section would look like this:

Here you can see that we have a JSON structure with the variable “countryCode”, which we’ve defined for our query, assigned with the value “PT”, to retrieve the data of Portugal.

Response:

Finally, after performing the query, we’ll get our Response:

You can see that it came in a JSON structure with the same format we defined in the request.

Putting everything together, you have something like this:

GraphQL as a POST:

Now that we have a notion of how GraphQL works and the sections that compose a GraphQL call, let’s take a look behind the scenes. As we said in the beginning, a GraphQL call performs a simple POST, enabling us to integrate with it in any platform that supports REST integrations, like OutSystems.

Let’s take a look then at how the example query GetCountryByName looks like in its REST format to have a general understanding of the request structure of a GraphQL call.

Getting the call structure:

After opening up the Web Inspector, we need to follow the steps below:

1. Go to the Network tab;
2. Find the request that you’ve made in the playground app;
3. Open the payload tab;
4. Copy the request payload;

In the end, the body of your request will look something like the following example:

As you can see, it is composed of three simple parts:

• “operationName” - string with the name you gave to your query;
• “variables” - structure that will have precisely the same value that you’ve placed on the variables section of your GraphQL call;
• “query” - string which will have the same value as your query in the GraphQL call;

When doing a query in GraphQL, these three parameters’ structure will always be followed, and only their values will change depending on the query itself.

Consuming GraphQL in Service Studio

Moving now to the OutSystems world, let’s continue with our GetCountryByName example. At this point, you might already have an idea of how to consume a GraphQL endpoint in OutSystems, since you’ve just learned what they look like in their REST form.

In theory, you simply have to create a REST integration in Service Studio; however, there are a few things to pay attention to, to ensure that everything works and that you reduce complexity to the minimum.

Removing New Lines:

Looking closely at the Request body presented above, we find that the “query” string is full of new lines, represented with “\n”. This character is not allowed when doing the call via OutSystems and will lead to runtime errors. So, when building the integration, we must make sure that we remove the unnecessary new lines and replace the structural ones with commas. In other words, the new lines that we used to define the structure of the Response in the GraphQL environment need to be replaced with commas, and the ones that don’t have any syntax value, need to be removed.

Below you can find the new version of the request:

Building the integration in Service Studio:

With the step above concluded, you can open Service Studio.

In the module where you wish to consume the endpoint, you can go to the Logic tab and then, right-clicking on REST, select “Consume REST API”. Finally, select “Add single method”.

In the new window, you must specify that this call is a POST, and then add the API URL, the Request without “\n” and an example of the Response, as displayed below:

At this stage, you can also add any Authentication settings you may need as you would for any other REST API.

After hitting the Finish button, you’ll end up with something like this:

Query variables:

Response:

As you can see, OutSystems built everything as expected. In our Request, we have the three parameters “Query”, “Variables” and “OperationName”. Even though OutSystems sees them as parameters, we know that both the Query and the OperationName, are constant for this call, since we always want to retrieve the same result structure. This means that you can assign default values to them, simplifying the way you consume the method afterward.

Please, remember to use the query string without “\n” and to set “Send Default Value” to Yes on both parameters.

Lastly, the only thing left to do is to encapsulate the method we just created in a Server or Service action to be consumed by another module. Even though you could consume the method directly, we highly recommend doing this last step, since it reduces the number of inputs and the complexity of the structures towards the consumer module.

In the encapsulating action, you need to add the inputs and outputs of your method, however, some simplification is due.

Regarding inputs, you don’t need the Query nor the OperationName, so you can simply ignore them. As for the Variables, they have a structure called “Variable” that encapsulates the value that you need to pass in. In this case, it looks like this:

Since we just need the string of the CountryCode, we can add a simple Text input to our encapsulating action without the need to make it of type “Variable”. If, in your case, you have an input of a more complex structure, you can still make the input of the encapsulating action of the type of the inner layer of the “Variable” structure, thus, removing one unnecessary layer that has no value for the consumer side.

Looking now at the output structure, we have the same case as we did for the “Variable”. Since the JSON response of the service always starts with “data”:{} the output of our GraphQL method will always be of type “Data”. This means that, as we did for the “Variable”, we can skip this layer in the output structure.

We can, therefore, set the output of our encapsulating action to the type of the inner layer of the “Data” structure. In our example, that would be “Country”.

Bringing this all together, we can then take a look at our encapsulating action:

Please, notice that you should leave the “Query” and “OperationName” empty since they’ll be populated with their default value. To minimize the number of assigns and variables, we also “expanded” the method’s input and passed the “CountryCode” directly. You’ll probably be able to do the same with your use case.

As for the Response, you can do a single assignment, as displayed below:

Consuming the GraphQL Method on a screen

After the completion of the encapsulating action, there’s nothing new. You can simply consume it on a screen as you would do for any other action. Below you can find an example of the GraphQL method being used in an OutSystems application to retrieve the data of Belgium. You can also test it yourself here.

That’s it! As you can see, after understanding that a GraphQL call is just a POST method with a specific structure, it becomes relatively simple to consume this type of method in OutSystems.

Please reach out if you have any comments or questions. We’d love to discuss this topic with you!

OutSystems is a potent tool, with a few tricks we can explore!

One such trick is the option to Add Multiple Methods from a REST API at once, with all inputs, outputs, and even descriptions! All you need is a JSON file with your App’s OpenAPI specifications (OAS). If your curiosity is ticking, we have an example of such a file at the end of the document, but that’s not important if all you want is to start coding!

In this post, you’ll learn:

• How to get the JSON file from:
  – OutSystems;
  – An External app, converting a YAML file into a JSON file;
• How to upload the JSON file in OutSystems;
• How to get the OAS for loads of public APIs for your projects;

How to get the JSON file?

You have two scenarios.

REST API Exposed in OutSystems:

If you‘re consuming a REST API exposed by another OutSystems application, it’s effortless since OutSystems does that documentation automatically. You can get the file by following the steps below in the Exposing application:

REST API Exposed in an External System:

However, in many situations you’ll be consuming endpoints from different sources and/or teams. Thankfully, our backend colleagues follow some specifications for documentation, one of them being the OpenAPI Specification (OAS), which, in their own words:

defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.

All you have to do is to ask them to provide you with the JSON file directly, since:

An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.

Alternatively, if they only provided you with the file in YAML format, you can convert it to JSON by going to https://editor.swagger.io, then importing the YAML file, and finally exporting it in JSON.

Then the JSON file will be saved in your disk, ready to be uploaded into the OutSystems Environment!

Upload the JSON file in OutSystems

If you have the JSON file, all you have to do in Outsystems is use the “Add multiple methods” option when consuming a REST API. Just follow the steps on the images below:

After a few seconds, you’ll see that OutSystems consumes all the methods in the specification! And just like that, you’ve saved a lot of time.

Bonus tip

If you want to consume a public API, like Google Calendar, or Microsoft Azure, you can find loads upon loads of YAML files created by the API-Guru team here https://apis.guru or in their GitHub repository https://github.com/APIs-guru.

We’ve used them in the past with great success!

Example of an OpenAPI specification in JSON

Just for curiosity’s sake, you can find below an example of an OpenAPI specification in JSON format:

{
   "swagger":"2.0",
   "info":{
      "title":"TaskAPI",
      "description":"DEMO API from ToDoItem\n\n## Authentication\n\nBasic Authentication is required for all requests.",
      "version":"1"
   },
   "basePath":"/REST_API/rest/TaskAPI",
   "schemes":[
      "https"
   ],
   "paths":{
      "/CompleteTask":{
         "put":{
            "tags":[
               "TaskAPI"
            ],
            "description":"Marks a task as complete",
            "operationId":"CompleteTask",
            "consumes":[
               "text/plain"
            ],
            "produces":[
               "application/json"
            ],
            "parameters":[
               {
                  "name":"TaskId",
                  "in":"body",
                  "required":true,
                  "schema":{
                     "type":"integer",
                     "example":1234567891234567,
                     "format":"int64",
                     "description":"Id of the task to complete"
                  },
                  "description":"Id of the task to complete"
               }
            ],
            "responses":{
               "200":{
                  "description":"True if an error ocurred",
                  "schema":{
                     "$ref":"#/definitions/Error"
                  }
               }
            }
         }
      },
      "/CreateTask":{
         "post":{
            "tags":[
               "TaskAPI"
            ],
            "description":"Creates a new task",
            "operationId":"CreateTask",
            "consumes":[
               "application/json"
            ],
            "produces":[
               "text/plain"
            ],
            "parameters":[
               {
                  "name":"Task",
                  "in":"body",
                  "description":"Task to create",
                  "required":true,
                  "schema":{
                     "$ref":"#/definitions/Task"
                  }
               }
            ],
            "responses":{
               "200":{
                  "description":"Id of the newly created task",
                  "schema":{
                     "type":"integer",
                     "example":1234567891234567,
                     "format":"int64",
                     "description":"Id of the newly created task"
                  }
               }
            }
         }
      },
      "/DeleteTask":{
         "delete":{
            "tags":[
               "TaskAPI"
            ],
            "description":"Deletes the given task",
            "operationId":"DeleteTask",
            "parameters":[
               {
                  "name":"TaskId",
                  "in":"query",
                  "required":true,
                  "type":"integer",
                  "x-example":1234567891234567,
                  "format":"int64",
                  "description":"Id of the task to delete"
               }
            ],
            "responses":{
               "200":{
                  "description":""
               }
            }
         }
      },
      "/GetTask":{
         "get":{
            "tags":[
               "TaskAPI"
            ],
            "description":"Returns a task by Id",
            "operationId":"GetTask",
            "produces":[
               "application/json"
            ],
            "parameters":[
               {
                  "name":"TaskId",
                  "in":"query",
                  "required":true,
                  "type":"integer",
                  "x-example":1234567891234567,
                  "format":"int64",
                  "description":"Id of the item to retrieve"
               }
            ],
            "responses":{
               "200":{
                  "description":"Retrieved item",
                  "schema":{
                     "$ref":"#/definitions/Task"
                  }
               }
            }
         }
      },
      "/SearchTasks":{
         "post":{
            "tags":[
               "TaskAPI"
            ],
            "description":"Gets a set of tasks based on the given search filters",
            "operationId":"SearchTasks",
            "consumes":[
               "application/json"
            ],
            "produces":[
               "application/json"
            ],
            "parameters":[
               {
                  "name":"Request",
                  "in":"body",
                  "description":"Search Filters",
                  "required":true,
                  "schema":{
                     "$ref":"#/definitions/GetTasksRequest"
                  }
               }
            ],
            "responses":{
               "200":{
                  "description":"List of founded tasks",
                  "schema":{
                     "$ref":"#/definitions/SearchTasksResponse"
                  }
               }
            }
         }
      }
   },
   "definitions":{
      "Error":{
         "description":"Error structure",
         "type":"object",
         "properties":{
            "HasErrors":{
               "type":"boolean",
               "example":false,
               "description":"True if an error ocurred"
            },
            "ErrorMessage":{
               "type":"string",
               "default":"",
               "description":"Message describing the error"
            }
         }
      },
      "GetTasksRequest":{
         "description":"Request structure of get tasks",
         "type":"object",
         "properties":{
            "UserId":{
               "type":"integer",
               "example":0,
               "format":"int32",
               "description":"Id of the user that created the tasks"
            },
            "Title":{
               "type":"string",
               "default":"",
               "description":"Title of the task, can be partial"
            },
            "Description":{
               "type":"string",
               "default":"",
               "description":"Description of the task, can be partial"
            },
            "DateTimeFrom":{
               "type":"string",
               "format":"date-time",
               "example":"2014–12–31T23:59:59.938Z",
               "description":"Initial date time for which to get tasks"
            },
            "DateTimeTo":{
               "type":"string",
               "format":"date-time",
               "example":"2014–12–31T23:59:59.938Z",
               "description":"Final date time from which to get tasks"
            },
            "Status":{
               "type":"string",
               "default":"",
               "description":"Can be "COMPLETED"; "OPEN"; "ALL""
            },
            "Pagination":{
               "$ref":"#/definitions/Pagination"
            }
         },
         "required":[
            "Status"
         ]
      },
      "Pagination":{
         "description":"Pagination data",
         "type":"object",
         "properties":{
            "Page":{
               "type":"integer",
               "example":0,
               "format":"int32",
               "description":"Current page number, 1 indexed"
            },
            "PageSize":{
               "type":"integer",
               "example":0,
               "format":"int32",
               "description":"Size of the page"
            },
            "TotalResults":{
               "type":"integer",
               "example":1234567891234567,
               "format":"int64",
               "description":"[OUTPUT] Total number of tasks that correspond to the given search filters"
            }
         },
         "required":[
            "Page"
         ]
      },
      "SearchTasksResponse":{
         "description":"Response Structure for the SearchTasks Method",
         "type":"object",
         "properties":{
            "TasksList":{
               "type":"array",
               "items":{
                  "$ref":"#/definitions/Task"
               },
               "description":"List of founded tasks"
            },
            "Pagination":{
               "$ref":"#/definitions/Pagination"
            }
         }
      },
      "Task":{
         "description":"Single task",
         "type":"object",
         "properties":{
            "Id":{
               "type":"integer",
               "example":1234567891234567,
               "format":"int64"
            },
            "Title":{
               "type":"string",
               "default":"",
               "description":"Title of the task"
            },
            "Description":{
               "type":"string",
               "default":"",
               "description":"Small descriptor of the task"
            },
            "IsCompleted":{
               "type":"boolean",
               "example":false,
               "description":"True if the to do task is completed"
            },
            "CreatedBy":{
               "type":"integer",
               "example":0,
               "format":"int32",
               "description":"Identifies the user that created this task"
            },
            "CreatedAt":{
               "type":"string",
               "format":"date-time",
               "example":"2014–12–31T23:59:59.938Z",
               "description":"Date time when this task was created"
            },
            "CompletedAt":{
               "type":"string",
               "format":"date-time",
               "example":"2014–12–31T23:59:59.938Z",
               "description":"Date time of when the task was completed; nulldate if not completed"
            }
         },
         "required":[
            "Id",
            "Title",
            "IsCompleted",
            "CreatedBy",
            "CreatedAt"
         ]
      }
   },
   "securityDefinitions":{
      "basic":{
         "type":"basic"
      }
   },
   "security":[
      {
         "basic":[
            
         ]
      }
   ],
   "tags":[
      {
         "name":"TaskAPI"
      }
   ]
}