Server Workflows

Server workflows are workflows that run on the Workflow server, instead of on a client. Specifically, server workflows run in the VertiGIS Studio Workflow Server component of an on-premises VertiGIS Studio Workflow installation.

Server workflows require on-premises Workflow. Cloud Workflow cannot run server workflows.

Running workflows on the server allows you to do certain tasks that you cannot do on the client, like querying databases, managing files on the server, and sending email. The activities that perform such server-side tasks cannot be used in client workflows. For example, the Run SQL Query, Write File, Send Email, and Create Download activities can only be used in server workflows.

Many activities can be used in both server workflows and client workflows. Other activities can only be used in client workflows. For example, user interface activities, like Display Form, Prompt, and Alert cannot be used in client activities. Server workflows cannot interact with the end user.

When you create a server workflow, the Toolbox only shows activities that work in server workflows. This prevents you from using activities that are not supported by VertiGIS Studio Workflow Server. Build the workflow the same way you would build a client workflow, by dragging activities to the design surface, connecting them into a flowchart, and configuring their inputs.

The most common scenario uses a combination of client and server workflows. The client workflow controls the user interface and calls the server workflow to perform the server-side functionality.

See Methods to Create a Workflow for instructions on creating server workflows.

Test Server Workflows

To test a server workflow, run it in the Sandbox just as you would a client workflow.

The verbose log does not log server workflows. If there is an error in a server workflow, the log will provide a link to an additional log to help you debug the server workflow.

After you create a client workflow that will run the server workflow, run the client workflow in the Sandbox. This not only tests the client workflow, it also tests the server workflow in the context of the client workflow. Use your browser's console to see the inputs that are passed to the server workflow and the outputs that the server workflow returns.

Run Server Workflows

To run a server workflow, add a Run Workflow activity to a client workflow and configure the activity to run the server workflow. When the Run Workflow activity executes in the client workflow, the server workflow runs.

You can pass inputs from the client workflow to the server workflow by configuring the Run Workflow activity's Arguments input. The server workflow brings in the inputs using a Get Workflow Inputs activity.

You can also pass an output back from the server workflow to the client workflow. To return an output, configure a Set Workflow Output activity in the server workflow. The client workflow accesses the output through the Run Workflow activity's result output.

You cannot export a server workflow to JSON and run it from somewhere else like you can a client workflow. Server workflows can only run on the server.

Another option is to configure a host application to run the server workflow directly. However, this approach is less common as it does not provide much (if any) user experience. In most cases, you will want to provide a user experience that prompts the user for input to the server workflow and then gives feedback when the server workflow completes.

For more information, see Host and Run Client Workflows.

Main Steps to Create and Run a Server Workflow

The main steps to create and run a server workflow are as follows:

1. Create the server workflow.

   • If the server workflow takes inputs, use a Get Workflow Inputs activity to get the inputs.

   • If the server workflow produces an output that you want to pass back to the client workflow, use a Set Workflow Output activity to set the output. The client workflow will use the name that you specify in the activity's Name input to access the output.

2. Configure a client workflow to run the server workflow.

   • Add a Run Workflow activity to the client workflow and configure the activity to run the server workflow. If the server workflow takes inputs, specify the inputs in the Run Workflow activity's Arguments input.

   • After the Run Workflow activity, access the output of the server workflow using an expression like =$runWorkflow1.result.Name, where Name is the name that you specified in the Set Workflow Output activity's Name input in the server workflow.

3. Run the client workflow.

Create and Run a Server Workflow

To create and run a server workflow:

Step 1: Create a server workflow

1. Sign in to Workflow Designer in your on-premises installation of VertiGIS Studio Workflow.

2. Create a new server workflow using one of the methods described in Methods to Create a Workflow.

   You can view VertiGIS Studio Workflow Server's URL on the Deployment panel. To open the Deployment panel, click Info in the sidebar and then click Deployment.

3. Build the workflow by adding, configuring, and connecting activities. If the workflow will take inputs from the client workflow that will run it, use a Get Workflow Inputs activity to get the inputs. If the workflow produces an output you want to pass back to the client workflow, use a Set Workflow Output activity to set the output. The client workflow uses the name that you specify in the activity's Name input to access the output.

4. Test the workflow by running it in the Sandbox.

   You can run a server workflow directly in the Sandbox. You do not have to run it from a client workflow.

   You cannot use the console to debug server workflows. When a server workflow has a run-time error, the console provides a link to a separate log to help you debug the workflow.

5. Press Ctrl+S to save the workflow.

6. Keep the server workflow open in Workflow Designer so you can access it in the next step.

Step 2: Configure a client workflow to run the server workflow

1. Open or create a client workflow in your on-premises installation of Workflow Designer.

2. At the point in the client workflow where you want to run the server workflow, add and connect a Run Workflow activity.

   Configure the activity:

   1. In the Url input, paste the URL of the server workflow.

      You can get the server workflow's URL from the Info panel.

   2. If the server workflow takes one or more inputs, specify name/value pairs for the inputs in Arguments.

      For example: { "name1": "This is a string"; "name2": 42 }

3. If the server workflow produces an output, add activities to process the output.

   Access the output using an expression like =$runWorkflow1.result.Name, where Name is the name that you specified in the Set Workflow Output activity's Name input in the server workflow.

4. Test the workflow by running it in the Sandbox.

   This tests the server workflow in the context of the client workflow.

5. Press Ctrl+S to save the workflow.

Step 3: Run the client workflow

Configure an application to host the client workflow. Run the client workflow from the host application.

For instructions on configuring host applications, see Host and Run Client Workflows.

Example - Use a Server Workflow to Query a Database

A common use for server workflows is to query a database. Typically, you will use the data table returned by the query in a form so the user can see and interact with the query results.

This example shows you how to query a database in a server workflow, return the data table to the client workflow, and use column values to populate a Drop Down List. Instead of using a Drop Down List, you could equally as well use an Auto Complete element or any other form element that has items.

The server workflow uses a Run SQL Query activity to query the database. The Run SQL Query activity returns a data table, which is a collection of objects with properties that represent columns. The server workflow uses a Set Workflow Output activity to return the data table as its output.

The client workflow runs the server workflow using a Run Workflow activity. To use the query results in a form, the client workflow has a Display Form activity with a Drop Down List form element. Because the data table is a collection, the client workflow uses a Get Form Element Items From Collection activity to convert a particular column of the data table to items that can be used to populate the Drop Down List. The Set Form Element Items activity populates the Drop Down List with the items.

To convert a data table to a feature set instead of form element items, use the Convert Data Table To Feature Set activity.

 

To use a server workflow to query a database and return the query results to the client workflow:

Step 1: Create the server workflow

1. Create a new server workflow using one of the methods described in Methods to Create a Workflow.

2. Add the following activities and connect them in the given order:

   • Run SQL Query (query1)
   • Set Workflow Output

3. Run SQL Query (sqlQuery1):

   1. Provider Name: Click in the Provider Name box to open a Drop Down List of data providers and select the provider for the database you are going to query.

   2. Provide the database's connection information:

      • Connection Config Name: If you have configured the database's connection string in the databasesettings.json file, type the name from databasesettings.json in the Connection Config Name box.

      • Connection String: If you have not configured the database's connection string in the databasesettings.json file, type the database's connection string in the Connection String box. For information on storing connections strings, see Database Connections for Server Workflows.

   3. Command Text: Type the SQL statement that you want to use to query the database. For example:

      SELECT * FROM COMPANY.CUSTOMERS ORDER BY NAME

      For security reasons, you cannot use an expression to define the SQL statement.

   4. Parameters: If you need to inject values into the SQL statement, specify them as name/value pairs in the Parameters input and use the names as variables in the Command Text input.

4. Set Workflow Output:

   1. Name: Type a name for the output, for example, customersDataTable.

      You will use the name in the client workflow to access the data table.

   2. Value: Set Value to the output of the Run SQL Query activity: =$sqlQuery1.dataTable

5. Press Ctrl+S to save the workflow.

6. Open the Info panel and copy the workflow's URL from the Workflow URL box.

   You will need the URL in the next step.

Step 2: Create the client workflow

1. Create a new client workflow.

2. Add the following activities and connect them in the given order:

   • Run Workflow (runWorkflow1)
   • Display Form

3. Run Workflow: In the Url input, paste the server workflow's URL.

4. Run the workflow in the Sandbox and press F12 to open the console. To view the data table returned by the query, expand the object named after the Set Workflow Output activity's Name input, for example, customersDataTable.

   This allows you to examine the data table in your browser's console. It also allows you to get the field name to populate the Drop Down List.

5. Display Form:

   1. Double-click the Display Form activity to edit it.

   2. Add a Drop Down List form element.

   3. Type a title for the Drop Down List in the Title box.

   4. In the Options area, select Use a subworkflow from the Drop Down List and click OK.

   5. Click Blank to use the Blank template.

      A blank subworkflow opens on the design surface.

   6. Add the following activities and connect them in the given order:

      • Get Form Element Items From Collection (formElementItems1)
      • Set Form Element Items

   7. Get Form Element Items From Collection:

      • Collection: Set the Collection input to =$runWorkflow1.result.Name, where Name is the name that you specified in the Set Workflow Output activity's Name input, for example: =$runWorkflow1.result.customersDataTable

      • Label: Type or paste the name of the field to use to populate the Drop Down List.

        You can get the field name from the console.

   8. Set Form Element Items:

      • Items: Set the Items input to the output of the Get Form Element Items From Collection activity: =$formElementItems.items

6. Run the workflow in the Sandbox.

   When the form displays, open the Drop Down List to see the field values from the data table. The items in the Drop Down List match the column values shown in the console.

7. Press Ctrl+S to save the workflow.