Goes through the steps to create and run an app on the SLINGR platform.

We know that the best way to understand and learn SLINGR is to get something done, so in this tutorial we will go step by step through the creation of an app from scratch, so you have the opportunity to see the whole process.

This is a very simple app and won’t go through all the features of the platform. The goal is that you get a general idea of how it works.

If you just want to see the results of the app, you could create a new app and use the Simple Task Manager app as the template. The only thing you will need to do is configure the Slack integration as explained in section Integrations.

Description of the app

We will be creating a very simple task manager app. There will be tasks that will have a workflow from its creation until completion. Users can create tasks, assign them to other users, and send notifications to Slack channels.

1. Create the app

We assume you already have a developer account at slingr.io. If not, go ahead and create one.

Once you are logged into SLINGR, you should create a new app:

  1. Click on the Create button on the top-right of the Apps section.
  2. Fill in the app label and name. Name musty be unique in the platform.
  3. Select SLINGR Free as the plan for your app.
  4. Select the option to start from scratch.
  5. Wait until the app is created. This takes a minute to complete.

Once your app is created you will see its details. By default you will be the owner of the app and you will have developer permissions for the development environment, which is created by default.

In the details of the environment you will be able to navigate to the different components of the app:

Development environment

  • Go To App: it will take you to the running app. Right now it doesn’t make much sense because we haven’t done anything yet so it’s empty.
  • Monitor: from there we can see the status of the app, background jobs, logs, etc. If you need to know what’s going on, this is the place to look at.
  • Builder: this is where we will develop our app, the app builder.

As our new app is empty, the first thing we need to do is go to the app builder by clicking on the Builder button. That will automatically open the builder in a new tab so we can follow with the tutorial.

2. Create tasks entity

Once you get into the app builder, it is time to start developing the app. The first thing we will do is to create the tasks entity, which will contain the definition of tasks in our app:

  1. In the left menu, go to Model > Entities.
  2. Click on the Create button on the top-right of the listing.
  3. Fill in the label with Tasks and the name will auto-complete with tasks when you move to another field.
  4. Click on Create. This will create an empty entity and you should see this in your left menu:

    New tasks entity

You will see that almost all elements will require a label and a name. The label is a human-friendly name, while the name is an internal identifier that you will likely use in your scripts to reference the element. Usually name does not allow spaces or special characters and must be unique in its context. We suggest to keep names as stable as possible to avoid having to make changes in your scripts.

Now it is time to create the fields inside the tasks entity. We will create the following fields:

Label Name Type Required Default value Notes
Number number Auto increment - - This a number that will be incremented for every new task created.
Title title Text Yes - The title of the task.
Status status Choice Yes To Do

This is the status of the task. Possible values will be To do, In progress, Done and Archived

Description description HTML No - A longer description of the task.

In order to create these fields, do the following:

  1. Select Model > Entities > Tasks > Fields on the left tree.
  2. Click on the Create button on the top-right of the listing.
  3. There you will need to complete the basic information: label, name, type and multiplicity. Depending on the type you might see some additional options at creation time, which is the case for the Status field where you will need to add the three possible statuses: To do, In progress, Done and Archived. Leave the suggested name for all these possible values:

    Status field

  4. Clicking on Save and edit will create the field and will open the details view for that field, where you will be able change other settings, like the default value and required flag. In our sample app we need to take care of the following things for these fields:
    • Title: the setting Required should be Always.
    • Choice: the setting Required should be Always. Also, in Default value you should put Value and then select the value To do from the dropdown.
  5. Once you finish editing all the settings (like default value or required flag) click on Save and you will be back to the listing to add more fields by repeating the above steps.

You should end up with a structure like this:

Tasks fields

The final step for this initial setup of the entity is to define the record label. The record label is calculated for every record and it is something that will identify your record. It doesn’t need to be unique, but should be human-friendly.

To configure the record label go back to Model > Entities > Tasks in the left menu and do the following:

  1. Set the option Script for Record label.
  2. In the code editor below put this script:

    return record.field('number').val() + '. ' + record.field('title').val();
    
  3. You should see something like this:

    Record label

  4. Click on Apply to save changes.

3. Create basic view

Now that we have the entity, the next step is to create a view so we can see something in our app. For that we will create a simple grid view that will allow to list, create, edit and delete tasks.

To create the grid view follow these steps:

  1. In the app builder, in the left menu select Model > Entities > Tasks > Views.
  2. Click on the Create button on the top-right of the listing and select the option Add grid view.
  3. Fill in the form with the following values:
    • Label: All tasks
    • Name: allTasks
    • Columns: Number, Title, Status
  4. Click on Create to complete the creation of the grid view.

Once we have the view we need to indicate how to navigate to it. We will use the left menu of the app for that, so in the left menu of the builder go to User interface > Left menu and follow these steps:

  1. Click on Add new menu entry on the top-right of the listing, and then click on the option Add view entry.
  2. Fill in the form wit the following values:
    • View: All tasks
    • Label: All tasks
    • Icon: view-list icon (you can filter icons by typing the name)
  3. Finally click on Create.

4. Test your app

Now we have the very basic to see something on our app! It is time to move our work from the app builder to the app runtime. This process is called Push changes and can be accessed from the top-right menu in the app builder:

Push changes menu

When you click on it you will see a modal showing the changes that will be pushed to the runtime and lets you write some description of the changes you did, which is optional.

Click on the button Push changes. Once all chages have been pushed, you will see a success message and you are ready to test your app! For that go back to SLINGR and see the environment settings:

Development environment

There click on Go To App, which will take you to your app. It should look similar to this:

App runtime

There you will be able to create new tasks, see and edit existing ones, as well as delete them. You can also filter tasks using the listing headers, export and import records. This has been all created automatically from your app definition!

5. Adding actions and define workflow

You already have the basic operations to create, edit and delete tasks. However it would be better to have a custom workflow that enforce some rules. For example a task can only be moved to In progress if it is in the status To do.

In order to create the workflow we will do the following things:

  • Create actions to move the issue through the different statuses.
  • Do not allow to manually modify the status.

Let’s start with the creation of the actions. For that you will need to go Model > Entities > Tasks > Actions in the left menu of the app builder and do the following things:

  1. Click on the Create button on the top-right of the listing.
  2. For Label put Start work and for Name leave the default value (startWork).
  3. In Preconditions you will indicate in which cases the action can be executed. For the action startWork the precondition is that the field Status must be To do. This can be indicated with an expression, so select the option Expression for Preconditions. Then you will need to setup the following expression by clicking on Add new rule and configure it like this:

    Action's precondition

  4. In field Action script add the following script to the body of the function:

    record.lock(function(record) {
        record.field('status').val('inProgress');
        sys.data.save(record);
    });
    
  5. Leave other fields as they are and click on Create.

Then we need to create the following actions using the same steps as above:

Label Name Precondition Action script
Complete complete

Status equals to In progress

record.lock(function(record) {
   record.field('status').val('done');
   sys.data.save(record);
});
Archive archive

Status NOT equals to Archived

record.lock(function(record) {
   record.field('status').val('archived');
   sys.data.save(record);
});
Stop work stopWork

Status equals to In progress

record.lock(function(record) {
   record.field('status').val('toDo');
   sys.data.save(record);
});
Reopen reopen

Status equals to Done or Archived

record.lock(function(record) {
   record.field('status').val('toDo');
   sys.data.save(record);
});

Good, now you have all the actions to manage the workflow! However there is one problem: anyone can just change the status field by simple editing the task. This is not what we want; instead we want to enforce people to follow the workflow we defined.

In order to prevent people from changing the status in an invalid way, what we will do is make it read-only:

  1. Go to Model > Entities > Tasks > Fields > Status in the left menu.
  2. Select the tab Display options.
  3. For the option Read only select Always.
  4. Save changes by clicking on Apply.
To keep it simple, we just made the field read-only. However the correct way to do it is to remove permissions to change that field, which will be enforced at the API level and not just he UI. We will see that later.

Finally, to make it easier to access actions from the grid view, we will enable actions there:

  1. Go to Model > Entities > Tasks > Views > All tasks in the left menu (you can also find the same element under User interface > Grid views > All tasks).
  2. Inside List settings, set the option Show actions to All and set the flag Show actions column.
  3. Save changes by clicking on Apply.

Now we are ready to push changes and see our workflow in place! So go ahead and push changes by using the option Push changes in the top-right menu of the app builder.

If you now go to your app you will see the actions are available in the grid view as well as in the read-only view of the tasks:

Actions column in grid view

Actions in grid view

Actions in read-only view

6. Add cards view

We already have our data model as well as our workflow defined. However we can make our app a lot fancier by using cards views. To give you an idea of what we are talking about, here is how it will look like:

Tasks board

Now let’s create the cards view:

  1. Go to Model > Entities > Tasks > Views in the left menu.
  2. Click on the Create button on the top-right of the listing and select Add cards view.
  3. Fill in the form with:
    • Label: Task Board
    • Name: taskBoard
  4. Click on Create and edit.

Once you created the cards view you will be seeing its configuration details. The first thing to do is to setup card settings:

  1. In the setting Header select Script and put the following code in the body of the function:

    return 'Task #' + record.field('number').val();
    
  2. In the setting Summary leave Field selected and in Summary field select Title.
  3. Save changes by clicking on Apply.

Now we should define the columns, but before doing that we will add a new field to the entity that will be needed to allow ranking records:

  1. Go to Model > Entities > Tasks > Fields in the left menu.
  2. Click on the Create button on the top-right of the listing.
  3. Fill in the form with:
    • Label: Rank
    • Name: rank
    • Type: Rank
  4. Click on Create and edit to save it.
  5. Go to the tab Display options.
  6. Set the option Visible to Never. This is to hide this field as we don’t want to show it to our users, we just will use it internally to keep the rank of tasks.
  7. Click on Save to save changes.

Now we are ready to create the columns in the cards view:

  1. Go to Model > Entities > Tasks > Views > Task board > Columns in the left menu.
  2. Click on the Create button on the top-right of the listing.
  3. Fill in the from with:
    • Label: To do
    • Filters: Status equals to To do
    • Set the flag Allow to rank records and select the field Rank in Rank field
  4. Click on Create to save the column.

Repeat the same process to create these two additional columns (don’t forget to configure the rank of records!):

Label Filters
In progress

Status equals to In progress

Done

Status equals to Done

Once you have the columns we need to define the transitions that will allow to move a card from one column to another:

  1. Go to Model > Entities > Tasks > Views > Task board > Transitions in the left menu.
  2. Click on the Create button on the top-right of the listing.
  3. Fill in the form with:
    • Label: Start work
    • Source column: To do
    • Target column: In progress
    • Action: Start work (tasksStartWork)
  4. Click on Create to save the transition.

Repeat the same process to create these other transitions:

Label Source column Target column Action
Complete In progress Done Complete (tasksComplete)
Stop work In progress To do Stop work (tasksStopWork)
Reopen from done Done To do Reopen (tasksReopen)

We are almost there! We will do a few improvements:

  1. Go to Model > Entities > Tasks > Views > Task board > CRUD actions > Tasks in the left menu.
  2. For Create, Read and Update set the flag Open in modal and click on Apply. This will allow to open tasks in a modal in this cards views.
  3. Now go to Model > Entities > Tasks > Views > Task board in the left menu.
  4. Inside Cards settings, in the setting Show actions select Some.
  5. Then in Available actions click on Add and select the action Archive (tasksArchive). This is to be able to archive tasks because we didn’t create a column for the Archived status to keep this view clean.

Finally let’s add the new view to the navigation:

  1. Go to User interface > Left menu.
  2. Click on the Add new menu entry button on the top-right of the listing and select Add view entry.
  3. Fill in the form with:
    • View: Task board
    • Label: Task board
    • Icon: select the one you like the most!
  4. Click on Create to save the menu entry.
  5. Move the new menu entry to the top. You can do that using drag and drop with the arrows next to the checkbox in the listing of the menu entries:

    Sort menu entries

Well, we are done! Now let’s push changes to see the results.

7. Test your app

Now we have the resulting app:

Tasks board

Here are some of the things you can do from there:

  • Create new tasks in a popup:

    Create task

  • You can move tasks from one column to another:

    Drag and drop tasks

  • You can archive tasks as well as perform the basic CRUD operations:

    Actions

  • You can rank tasks (move them up and down):

    Rank tasks

8. Permissions

Now we will add some permissions so you can see how groups and users work. This is what we will do:

  • Add a new field assignee to the tasks entity. This will be a field of type User that will point to the user assigned to complete the task.
  • We will create two groups: Manager and Support. Users in the first group will have access to all tasks, while users in the second one will only be able to see tasks assigned to them and won’t be able to reassign tasks or change title of a task.
  • None of the groups will have access to change the status field manually.
  • We will create 3 users: 1 manager and 2 support users.
  • Finally we will test that everything is working as expected.

So let’s go to Model > Entities > Tasks > Fields and add a new field with label Assignee, name assignee and type User. Make sure to set the default value to be Current user:

Default value to current user

Make sure you saved your changes and move the field to be above Description.

Now let’s add the two new groups:

  1. Go to Security > Groups in the left menu.
  2. Click on the Create button on the top-right of the listing.
  3. Set label to Manager and name to manager and click on Create and edit.
  4. Now we need to add permissions to access entities and views. Go to Security > Groups > Manager > Entity permissions.
  5. Select the Task entity and then click on Apply permissions:

    Apply permissions option

  6. There select the option Read/write and click on Apply.
  7. Then click in the configuration button which is on the last column (Edit) and configure fields permissions so fields Status and Rank are read-only

    Apply permissions option

    Ths is the correct way to enforce permissions instead of just making the field read-only in the UI.

  8. Finally click on the Apply button on the top-right of the listing to persist changes.
  9. Then go to Security > Groups > Manager > View permissions.
  10. Set the flag in the column Permission for both views:

    Apply permissions option

  11. Finally click on the Apply button on the top-right of the listing to persist changes.

Then repeat the same process to create the Support group. However we will edit permissions for the Tasks entity:

  1. Once you created the Support group and you added entities and views permissions, go to Security > Groups > Support > Entity permissions in the left menu.
  2. In the Tasks entity, click in the button under the Edit column.
  3. Entity permissions should be configured like this:

    Entity permissions

    This is what’s configured:

    • No create permissions
    • Access is only allowed if the assignee is the same as the current user, which means support user will only see tasks assigned to them.
    • Edition is always allowed (as long as they have access permission)
    • No delete permissions
  4. Field permissions should be configured like this:

    Field permissions

    With those settings we remove write access to assignee, title and status.

  5. Action permissions should be configured like this:

    Actions permissions

  6. Save changes by clicking on Apply.
  7. Configure view permissions in Security > Groups > Support > View permissions in the same way as for managers.

Now we have the two groups created and permissions have been defined. Let’s push changes so we can use this groups when creating users.

It’s time to create a few users (make sure you pushed changes before):

  1. Go to Security > Users in the left menu.
  2. Click on the Create button on the top-right of the listing.
  3. Fill in the from with:
    • First name: Manager1
    • Last name: Test
    • Email: manager1@test.com
    • Generate Password: true
    • Groups: add the Manager group as Primary
  4. Click on Create to save the user.

Then repeat the same process for these users:

First name Last name Email Primary group
Support1 Test support1@test.com Support
Support2 Test support2@test.com Support
You don’t need to push changes when working with users because users are modified directly in the runtime as they aren’t part of the metadata of the app.

Now we have permissions defined and users to test, so let’s go to the app runtime:

  • If you logged in from your developer user you will be able to switch to any other user. This can be done with the option Switch user in the top-right menu of the app runtime:

    Switch user

    Switch to the user Manager1 Test.

  • You should be able to see all tasks.
  • Create two tasks: assign one to Support1 Test and the other to Support2 Test.
  • Switch to user Support1 Test using the Switch user option in the top-right menu.
  • You should only see the tasks assigned to Support1 Test.
  • Switch to user Support2 Test using the Switch user option in the top-right menu.
  • You should only see the tasks assigned to Support2 Test.
  • You can go back to your developer user with the same Switch user option.

That’s the basic about permissions, but there are more features to allow more fine-grained permissions management, just check the Developer’s reference for more information.

9. Integrations

In SLINGR, in order to integrate with other services you will use “endpoints”. They make it simple to connect to other applications like Google Calendar, Twilio, Chargify, QuickBooks, etc.

The SLINGR Free plan has a limited number of endpoints available (if you need more, you can upgrade to another plan!), where we can find the HTTP endpoint that allows to make generic HTTP requests. This is perfect because many services have REST APIs that can be accessed with regular HTTP requests.

Even though you can make requests to many services using the HTTP endpoint, it is better to use specific endpoints as they provide much more features and simplify the interoperability with the other service.

In this case we will use the HTTP endpoint to post notifications about new tasks in a Slack channel. This means that in order to proceed you will need to have a Slack account with access to a Slack workspace. You can create your own for free at slack.com.

Once you have your Slack workspace, you will need to create a Slack App at api.slack.com/apps. Make sure that you do the following things:

  • You configure your app to have a bot
  • You install your app into your workspace

These are the sections where you’ll find those things:

Slack app configuration

Once you install the app in your workspace, you will find the Bot User OAuth Access Token, which is in the section Install App. Copy it because we will use it in our app. However, instead of hard-coding it in the code, we will do something much better: we will use environment variables.

Environment variables allow to store credentials or settings that need to be secure (they are encrypted) and that probably change from environment (for example, you probably will use a different Slack account in dev than in prod). So let’s add the environment variables that we will need:

  1. Go to the app builder
  2. Go to Environment settings > Environment variables in the left menu
  3. Click on Create to create a new environment variable
  4. Put SLACK_TOKEN as the name of the variable and paste the bot token that you copied from your Slack app
  5. Click on Create to save the variable
  6. Click on Create again to add another environment variable
  7. Name it SLACK_CHANNEL and put the ID of the channel where you want to post your messages
  8. Click on Create to save the variable

You should end up with something like this:

Environment variables

OK, now we need to write the code that will be sending the notification. As this function could be reused in different places of the app, we will put it in a library. Libraries are great to put code that you will reuse from different places in your app. Let’s do it:

  1. Go to Model > Libraries in the left menu
  2. Click on Create, at the top of the panel that stands in the middle
  3. Name the library slack and click on Save
  4. Then, in the code editor on the right put the following code:

    exports.sendMessage = function(message) {
      app.endpoints.http.post({
        path: 'https://slack.com/api/chat.postMessage',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
        },
        body: {
          token: '${SLACK_TOKEN}',
          channel: '${SLACK_CHANNEL}',
          text: message      
        }
      });
    };
    
  5. Click on Save to save the library

Here there are a few things to notice:

  • The way to “export” symbols in the library is by adding them inside the object exports. That’s why we put our function sendMessage in exports, so we can call it from other places of our app.
  • In order to use environment variables, you need to surround them with ${}. Those will be placeholder that will be replace by the actual value of the variable in that environment.

So we already have the Slack app, the configuration in environment variables and the library with the code to send a notification to a channel. The only thing we are missing is add something that triggers the notification when a new task is created. And here is were listeners comes into action!

Listeners allow to react to events happening in your app. The event could be something that happen in another app connected through an endpoint, it could be a timer or changes in the data of your app, which is what we are looking for. Let’s create the listener:

  1. Go to Model > Listeners in the left menu (there is also a shortcut inside the entity)
  2. Click on Create to setup a new listener
  3. Put Send notification to Slack as the label and leave the calculated name
  4. Select Data as Type
  5. In Entity select the Tasks entity
  6. In Rules click on Add New:
  7. In Source events select User Events and Script Events
  8. In Event select On record created
  9. Leave Condition to None
  10. Click on Add to add the rule
  11. Set the flag Execute in the background
  12. Write this script in Action:

    app.slack.sendMessage('Task created: '+record.label());  
    

    Here you can see how we call the libraries, using the prefix app..

  13. Finally click on Create to save the listener

Listener

Alright, we are ready to test our integration! Let’s push changes.

Now, when you create a new task, you should see the notification in your Slack channel. If you don’t see it, it means there is a problem. But don’t worry, keep reading to see how you can find out what’s going on by using the app monitor.

10. Monitor your app

We are done with the development of the app, but it is good to mention that you can see what’s going on in your app in the app monitor.

To access the app monitor your should click on the Monitor button in the environment settings:

Monitor access

From there you can have information of your running apps. For example you can see the logs of your app in the Logs section:

Logs

Or see the status of background jobs:

Jobs

Back to top