Tutorial

This tutorial is a hands-on experience in which you build a Soiree solution from scratch. The tutorial will introduce you to all the concepts needed to begin creating your own solutions.

If you intend to actually perform the lesson exercises we recommend you complete them in order because each lesson builds on the prior lessons. Otherwise, you may want to simply browse through the lessons and use the examples to guide you in building your own solution.

Ready to build something with Soiree? Dive into these lessons.

The water is not too deep
You do NOT need programming experience in order to complete these lessons. We guide you through each lesson step by step. So, come on in. The water is fine. [ who wouldn’t enjoy a good pool party? ]

Introduction to the Party Pool

It is time to meet the solution you will be creating in these lessons.

We have attempted to make it just big enough to allow you to experience much of what Soiree has to offer for real-world solutions while at the same time keeping it just small enough so that the design does not obscure the mechanics of building the solution.

The Party Pool is a product you would sell to party planning companies. It will provide the ability to

  • Maintain a list of parties
  • Maintain a list of food items that can be offered at parties – including photos. [ I love seeing food! ]
  • For each party it can
    • Define the menu to be served
    • Define the list of guests that will be attending
    • Send email invitations to the guests
    • Track RSVP responses
  • Support multi-tenancy. This is the ability to support multiple customers [ party planning companies ] on a single instance of the solution. This allows party planning companies to sign-up and start using your solution without you having to create another technology stack for them [ think hardware, SxServer, database].

You will get to do

  • User experience design
  • Database access
  • Integration of information from multiple databases
  • user security
  • navigation menus
  • performance monitoring
  • image integration
  • drag and drop support
  • desktop solutions
  • iOS solutions
  • Android solutions

It’s time to jump into the party pool.

Let the party begin

As you go through the lessons keep an eye out for how Soiree leverages multiple disciplines in the development process. Soiree can be used by a single person very effectively, however, for larger teams Soiree helps you to achieve multiple lanes of expertise that increase the quality of your solution and the efficiency of your team. Look for the following



[ it sounds like we are talking about rolls and it is making me hungry ]

An Introduction to Soiree

Please look at the Tutorial Introduction before starting the lessons.

Preparing the Soiree Workbench and Lesson Database

Before you can build anything you need a good workshop. It just so happens that Soiree is a really great workshop and easy to set up. In this set of lessons you will prepare the Soiree workbench so that you may build your first of many solutions.

WARNING
Creating Soiree solutions can be highly addictive. Try to maintain a balanced life. [ you have been warned ]

Lesson 1 – Setting up the Soiree Workbench
Lesson 2 – Preparing a Java project for Soiree
Lesson 3 – Install the Demo database
Lesson 4 – Creating a Database Connection

Your first Scene

In this set of lessons you will build and use a scene. Let’s begin by describing what you will be creating.

  • A scene provides the user experience.
    Scenes provide the stage and props where your works of art will perform.
  • Scenes are packaged into Solutions.
    Solutions are the product entry points you provide to your customer. Just as a movie tells its story as it progresses from scene to scene a Soiree Solution unfolds across one or more scenes. In this initial set of lessons you will build a solution containing one simple scene which does not actually do anything. It just presents itself – just like walking into a party – it simply shows up.
  • Solutions run in a Soiree server.
    A server contains the under-appreciated crew who work in the shadows during a party and take care of everything to ensure the party is perfect and safe for everyone.
  • Servers may have one or more Soiree clients connect to them.
    What’s a party without having someone show up to enjoy it?
  • The Soiree client presents the solution to your customer.
    The client is where your scenes strut their stuff.

Let the party begin!

Lesson 5 – Creating a Scene
Lesson 6 – Creating a Product
Lesson 7 – Creating a Solution
Lesson 8 – Creating a Server
Lesson 9 – Starting and Stopping a Development Server
Lesson 10 – Creating SxServer Profiles
Lesson 11 – Starting the integrated desktop client

Bringing the Scene to life

Having your scene simply show up at your party is not enough. In this lesson you will learn how to get your scene involved in the action.

  • A Soiree scene may contain content that changes as the user interacts with it.
  • Layers provide the content of a scene.
    Layers are like clear panes of glass on which you can draw things.
  • Scenes may contain multiple layers.
    Scenes can unfold, react, and change by opening or closing layers.
    Multiple layers can be open at the same time – with each open layer adding its content to the overall scene.
  • Solutions can move from scene to scene.
    Your solution can unfold by transferring from one scene to another.
  • Unfolding Options
    Your solution can unfold by opening or closing layers in a scene or by transitioning from scene to scene. Either technique can look the same to your customer. Which should you choose? We will provide guidelines to help you answer that question as you progress through the lessons.
    For now, consider this: is your party’s food better served as a series of Hors d’oeuvres and meal courses or slammed into a blender and served in a bowl? [ it’s a matter of taste, organization, and manageability ]

Lesson 12 – Having fun with scene layers
Lesson 13 – Scene Transitions
Lesson 14 – Granting scene access to everyone

It’s all about the skin

What you have been creating up to this point is called a Soiree skin. A skin provides the ability to test drive the solution before you create it. You can think of the skin as a living / breathing specification for the solution. As you design the scenes and link them together you are providing an interactive expression of your design that should be in the hands of your customer very early in the development cycle.

We are not advocating that you skip the design process and begin ‘coding’. Skins are the design process.

Software development is a process of discovery. Let skins help you discover the best path to your destination.
Be sure to try on several skins before you commit to wearing one to the party you are hosting for your customer, and be sure to take your customer with you on this journey. Have your customer interact with the skins until they are certain you understand what they need. When your customer can see and touch an interactive skin they provide you with the type of responses you normally receive only after the product is deployed. Seeing and talking about a design may get you some good feedback but actually touching it and taking it for a test drive evokes a much richer and meaningful response from your customer. Knowing that type of information before you begin will go a long way to reduce cost and improve quality.

You will be your customer’s hero. Rather then telling them NO when they request a change (because it costs too much to make the change – or it’s already in production) you can say ‘YES, and how else can we improve the design?’.

Tip
You should not create ‘a skin’ from ‘a design’. You should create multiple skins as you discover the best design.
May the best skin win. [ we should have a skin contest! ]

Soiree skins are more cost effective and yield higher design fidelity than other design techniques

  • Skins are easy to create. [ and throw away ]
  • They provide more effective ‘post-production’ types of customer engagement at the beginning of the process.
  • Skins are transformed into the final product.
    You don’t create a design / prototype and then set it aside while developers reproduce the design in another technology.
  • The investment you make in the design process yields a second harvest as you enter the build phase. You get to retain your entire investment and accelerate your timelines. [ That is that like ordering food for 10 and getting enough food for 20. I’m getting hungry, I should look through the JARS again for something to eat. ]
[ Skins are the product. No, silly, they exist before you have a product. No they don’t, yes they do, no they don’t…
I think I am arguing with myself. Oh well, either way I am right.]

The Designer Role

The solution and scenes that you have been creating up to this point as part of what we call the designer role.

Consider establishing a designer role on your development team. A designer would be a person skilled in process flow and visual clarity. They are focused on process improvement and user experience. These designers can be fairly non-technical because strong spreadsheet or presentation skills are sufficient for skinning a solution. [ you mean I can fish for development resources outside of the over-tasked programmer pool? ]

Tip
Your customer should be part of the design team throughout the entire project.

During these lessons you will be transitioning in and out of the designer role as you create various aspects of the solution.

The Data Access Role

You will now be transitioning temporarily to the data access role.

It is time to install a tool that allows you to look at the contents of the tables. This will come in handy in future lessons as you begin adding data to these tables.
Lesson 15 – Install DBeaver

Here are the lessons for the data access role
Lesson 16 – Supporting Multiple Tenants
Lesson 17 – The party pool data model
Lesson 18 – Entity Definitions
Lesson 19 – Data Source Introduction
Lesson 20 – Create a Data Source
Lesson 21 – Create a Sequence
Lesson 22 – Create a Code List
Lesson 23 – Customize a Validation Pack
Lesson 24 – Using a Datasource

The Engineering Role

You will now be transitioning temporarily to the engineering role. The engineering role creates software that connects the user experience with the information stored in the database – and adds all those exciting functional bits that make the solution so very useful to your customer.

Soiree engineers have no need to touch the user interface [ unless they want to ]. Engineers excel at algorithms, data structures, design patterns, and programming languages. With Soiree they can [ and probably should ] remain focused in their area of expertise. Engineers use their skills to build glorious structures that are very real but only seen by those who can dive into the technical waters and survive.

Until now.

Soiree restructures the engineering process to produce nicely-packaged bits, called Agents, that can be readily seen, understood, and consumed by the designer.

This repacking of technology allows Soiree to re-wire the interaction between designer and developer.

  • The traditional approach often looks like this

    • The design team creates the conceptual model and then hands off the design to the engineering team.
    • The engineering team uses the design concepts to create the product as the designers cheer them on to victory.
  • With Soiree the process can look like this
    • The design team provides a skin that expresses the design.
    • The engineering team creates the bits that provide the muscle and structure beneath the skin.
    • The design team takes what the engineering team produced, assembles the final product, and delivers the solution to the customer.
    • These tasks are non-linear. They take place iteratively and in parallel.
      [ it’s a great way to speed up the delivery of a product ]

This approach provides the following benefits

  • It requires fewer hand-offs during the delivery cycle
  • It yields a product with higher fidelity to the intended design
  • It allows a broader set of skills to be actively involved in pulling the product to the finish line
  • It provides a more balanced work effort across the entire team
  • It allows everyone [ including the customer ] to see tangible progress as the product springs to life
Designers Rule!!
The people closest to the customer design the solution, assemble the final product, and deliver it.
[ hey, isn’t that a little rude to say that here in the engineering section?

It is time to introduce you to Soiree Agents.
[ just so you know, when you meet them they prefer a fist-bump instead of a formal handshake ]

Lesson 25 – Agent Introduction
Lesson 26 – Creating a Multi-Row Agent
Lesson 27 – Creating a Single-Row Agent

Adding Parties

It is now time for the design team to animate the skin by dropping agents into it.

Lesson 28 – Binding a Multi-Row Agent to a Scene
Lesson 29 – Adding rows to a list
Lesson 30 – Problem Resolution
Lesson 31 – Key Binding and Initial Focus Control
Lesson 32 – Dynamic Scene Reloading
Lesson 33 – Layout Rules

Advanced add mode options

In this lesson you will enhance the add process by providing default values. The key point to notice in this lesson is the clear line of responsibility between the design team and engineering team.

  • The design team is responsible for how things are presented
  • The engineering team is responsible for the values to be presented [ and their validity]

Lesson 34 – Preparing for add or replicate

Data Integration

Products frequently need to integrate information from multiple sources. Some systems may be designed to add a new set of features around an existing system. Others may simply need to pull information from various sources to provide a more complete picture of the organization’s operations.

The following lessons are designed to demonstrate the ease of data integration using Soiree.

The key points to be observed are these

  • Soiree can be used to combine information from multiple agents. [ we call this compositing ]
  • Each agent can choose its own source of information.
    This can be a relational database, web service, text file, spreadsheet, etc. Where the agent obtains its information is not important.
  • When Soiree composites agents they are fused together and operate as a single service.
  • The Soiree Pump provides very robust choreography of services – thereby eliminating the need for you to wire the services [agents] together.
    This allows designers to assemble the final solution once the engineers have delivered the agents.
  • Agent granularity can be as small as a single value in the overall data model.
  • The emergent data model is your friend – and is not limited to a single information source.
Compositing
Compositing is the combining of two or more agents to perform a singular task.

What you will be doing
The ACME Party Planning Agency is one of the tenants using your Party Pool solution. They have asked you to add a field for capturing a party theme which is a required value for every party. You have agreed to accommodate their request, however, you have determined this feature is not something you want to add to the core product for all customers.

You will be extending the data model to meet this requirement without making any changes to the existing database or agents.

Lesson 35 – The ACME Database
Lesson 36 – PartyTheme Datasource
Lesson 37 – Data Validation in an Agent
Lesson 38 – Composited Add
Lesson 39 – Element Visibility
Lesson 40 – Conditional Mode Execution

State Bound Layers and Global Agents

You have learned how to influence the visibility of an element using an agent. The next lesson will show you how agents can influence the visibility of an entire layer.

Lesson 41 – State bound layers and global agents

Viewing and Manipulating a Party

This series of lessons will have you enhance the solution so that you can view existing parties and make changes to them.

Lesson 42 – Agent Events and Row Selection
Lesson 43 – Deleting individual items in a multi-row agent
Lesson 44 – Updating items in a single-row agent

Managing Your Product

Check out these lessons to learn how Soiree helps you support a product once it is created.
Lesson 45 – Item References
Lesson 46 – Refactoring
Lesson 47 – Server Console – Initial Access
Lesson 48 – Performance Monitor
Lesson 49 – Execution Detail Logging

User Security Services

Soiree offers user security services for securing access to your product. Let’s do a quick fly-by of these services before we get into the details of how to use them. [ i love flying – but no barrel rolls, ok? well – maybe just one.]

Solutions requiring user authentication must provide a sign on scene. The sign on scene is something you create – this allows you to style it to fit the needs of your solution. However, you need not start from scratch because Soiree provides a sample sign on scene and agent which you may copy and use.

This diagram provides a peek at user security from the crow’s nest.



The following lessons provide details about Soiree’s user security services.
Lesson 50 – User Service
Lesson 51 – Rights
Lesson 52 – Security Groups

Soiree provides three ways to provision users

  1. Manually
    Lesson 53 – User Provisioning – Server Console
    Lesson 54 – User Provisioning – The Server Console and User Services
  2. Programmatically
    Lesson 55 – User Provisioning – API
    Lesson 56 – Auto Provisioning
  3. Through bulk load operations
    Lesson 57 – User Provisioning – Import Users
    Lesson 58 – User Provisioning – Mass User Group Assignment

Each user is assigned a unique identifier by Soiree. You can learn about it in this lesson
Lesson 59 – User Tokens and User Preferences

Session Management

The Soiree client you have experienced in the lessons up to this point consists of a single application frame on the desktop which contains a single scene. That is the most common way to present scenes but it is not the only way – especially for desktop solutions. Session management makes it possible to display more than one scene in an application frame.

Session management provides the environment in which scenes and agents operate. Each scene runs in a session. You can learn more about sessions in these lessons
Lesson 60 – Connections, Homes, and Sessions
Lesson 61 – Multiple Sessions
Lesson 62 – Sharing Information Among Agents
Lesson 63 – Cross-session Context
Lesson 64 – Solution Scene Control / Workflow
Lesson 65 – Session APIs

Authentication Services

You are nearly ready to authenticate people in the Party Pool solution. Let’s take a look at how to actually do user authentication before you add sign on processing to your solution.

Lesson 66 – User Authentication

It is now time to enhance the Party Pool solution to authenticate users.
Lesson 67 – Party Pool Sign On – Using the Sample Sign On Process
Lesson 68 – Authorizing Users to the Party Pool
Lesson 69 – Soiree Security Manager – Refining the user validation
Lesson 70 – Multi-tenant Sign On
Lesson 72 – Multi-tenant Provisioning

Navigation Services

Navigation services help a person move around inside a solution.

Movement within a solution rides on one of three rails

  1. Directed Movement
    This is navigation prescribed by the solution. Taking a user forward or backward through a predefined set of steps is one example. The user has no choice of where to go next (other than to leave the solution).
  2. Selected Movement
    This is navigation selected by the user. Providing a set of options to the user so they can select where they want to go next is a common way to provide selected movement.
  3. Adaptive Movement
    This is really just a variation of either directed or selected movement. It is navigation tuning itself to information contained in the solution or the user’s security profile.
    • Directed movement is adaptive if the direction of navigation is not statically defined and the same for all users.
      For example, if navigation can branch in one of many possible directions based on the type of item being added to a shopping cart then it is directed movement adapting to information about an item.
    • Selected movement is adaptive if the options presented to the user are not statically defined and the same for all users.
      For example, if the navigational aid shows only the places a person’s security profile allows them to go then it is selected movement adapting to the user’s security profile.

The following lessons describe what Soiree provides for each type of navigation
Lesson 73 – Directed Movement
Lesson 74 – Selected Movement

Navigation aids are something you design into your solution and you have all the power of scenes and their elements to support your design. There are even navigation specific elements in the more prescribed environments of iOS and Android. In addition, Soiree provides a menu service to assist you in providing scene navigation within your solution.

Soiree’s menu service offers the following

  • The items in a menu may be represented as text, an image, or both
  • The menus may be embedded anywhere you need to display a list of selectable scenes
  • The menus adapt to the user’s security profile. The user will only see those scenes they are allowed to access regardless of which scenes are defined to be on the menu.
  • Soiree provides a visual editor for defining the menu’s content
    • You may define menus as a simple lists of scenes
    • You may define menus as a hierarchical collections of scenes complete with sub-menu descriptions
    • You may define multiple menus for each solution.
      • The primary navigation menu(s)
      • Specialty menus used to display navigation choices at any point in a process flow
  • Soiree provides services to help you display the menu information in your solution
    • Menus may be displayed as a simple list
    • Hierarchical menus may be presented in an expandable tree
    • Hierarchical menus may be presented as a collection of parent and child menus. The user can move up and down through the menus before making their selection.

Here are the top three reasons for using Soiree menu services

  1. They are easy to create and use
  2. They adapt to the user’s security profile
  3. You remain in control of the presentation style

Lesson 75 – Creating a Menu
Lesson 76 – Displaying a menu
Lesson 77 – Menu Manager API
Lesson 78 – Sample Menus Unwrapped
Lesson 79 – Custom Menu-driven Workflows
Lesson 80 – Entity-aware Menus