PREVIEW

Working with App tasks

This tutorial guides you through the process of building an App task, which involves the following phases:

• Creating an action definition and uploading it in Action Center.
• Developing an action app within Apps, and setting up fields for each property defined in the action definition.
• Publishing the app and creating a workflow in either Studio Web or Studio Desktop using the Create App Task activity.

1. Create and upload the action definition

To link action fields with an app, you have to create a JSON schema, you need to create a JSON schema, called an action definition. This definition outlines the required action fields and specifies the allowed actions available when completing the action.

1. Prepare the action definition:
   1. Start by adding an open curly brace to indicate the start of the JSON object.
   2. Inside the JSON object, define the Name and Description properties as strings, along with their values.

      "Name": "Validate Document",
          "Description": "Validate and approve invoice",

   3. Add an Allowed Actions property as an array of strings to specify the allowed actions that you can take at the end of the action. The values should be the equivalent of Complete or Decline.

      "AllowedActions": [
              "Yes",
              "No"
          ],

   4. Add a Schema property and assign it an object that adheres to the JSON Schema standard: http://json-schema.org/draft-07/schema#.

      "Schema": {
              "$schema": "http://json-schema.org/draft-07/schema#",
              "type": "object",

   5. Within the properties object, define each property you want to include in the schema. For each property, specify its type and description.
      Each property in the Schema is the equivalent to the input fields you will add in the App action.

      "properties": {
                  "Description": {
                      "type": "string",
                      "direction": "in",
                      "description": "Validation message"
                  },
                  "invoice_document": {
                      "type": "string",
                      "direction": "in",
                      "description": "Document file."
                  },
                  "Comments": {
                      "type": "string",
                      "direction": "inout",
                      "description": "Approval or rejection comments"
                  }
              }

      Note: If the direction property is not defined, then the default value for it is inout (In/Out).
   6. If certain properties are required, include a required array, where you list the properties that you want to mark as required in the action.
   7. Close the JSON object by adding a closing curly brace.
2. Upload the action definition to Action Center:
   1. Open Action Center, navigate to Admin Settings, and select Tenant.
   2. In the Action Definitions tab, select Add Action Definition.
   3. Select Download action definition sample to download a sample JSON schema to help you prepare the action definition.
   4. Select Import from file, and select the JSON file you prepared earlier.
   5. Enter an appropriate name and description for the Action definition, and then select Create.

2. Create the Action app

Apps created using an integration for Actions are designed to be utilized within long-running workflows, and end users can access these apps only through interaction with the generated actions.

1. Open Apps within the organization where you uploaded the action definitions.
2. Create a new app from scratch, or choose a pre-made template that suits your needs.
3. Next to Add Control, select Add Any and then select Action.
   This step allows you to specify the action definition for this app. For this example, we are using the Validate Document action definition.
4. Select the tenant where you previously uploaded the action definition, and select Next.
5. On the left side of the Add action dialog, select the action definition you have created, and click Add.
   
   

   

   
   

   Visit Referencing an action definition within your app to learn more about using action definitions with your Action Apps.

6. Now you can start adding controls to your app.
   Ensure that the names of the app controls align precisely with the names used in the JSON schema of the action definition. For instance, if you include a document viewer control to display the invoice_document property from the action definition, name the control invoice_document.
   The input or output parameters of an action can be bound to any app control, by using the following syntax: Actions.<referenced_action_name>.<action_parameter_name>
   1. Create a blank page and add a Layout to it.
   2. Inside the Layout, add a Container, where you can add text box and image controls, to display the customer name and logo of the company that's validating the document.
   3. Inside the Layout, add a Container, where you place the Document Viewer control.
   4. Create a variable named var_invoice_file and add it as the Source of the Document Viewer control.
   5. Add another container inside the Layout, where you can add a Text Area on the left. As the Default text type in the following expression: Actions.Validate_Document.Comments.
   6. Add two Button controls responsible for completing the action and configure a rule to submit the action, corresponding to the Allowed Actions specified in the action definition:
      1. Go to Events and select Create rule.
      2. From the dropdown list menu, select Submit action.
      3. Under Action outcome, select the allowed action that you want the button to trigger when clicked: Yes or No.

      Visit Rule: Submit Action to learn about this specific rule.

7. Establish a link to a storage bucket where you'll upload the document before forwarding it as part of the action.
8. Publish the app, making it accessible to use within your Studio workflows.

   Visit Publishing an action app to learn more about the process of publishing an action app.

Note: Optionally, if you want to replace the action that you are using for your app, visit Replacing an action.

3. Create an App task inside a workflow

Create a workflow in Studio Web or Studio Desktop to download an invoice document from a Google Drive account. Upload the downloaded document to the storage bucket bound to your Action app. Next, add a User Action/App action activity to display the specific document for user approval or rejection. Assign the task to a user, await action completion, and resume the workflow. Log a message detailing the user's validation decision for the document.

1. Create a new project in Studio.
2. Add a Download File activity.
   1. Establish a connection to Google Drive inside the activity.
   2. In the File to download field, specify the name of the file you want to download.
   3. Under the Output section, create a variable to store the downloaded file.
      For this example, name the variable downloadFile.
3. Add an Upload Storage File activity to upload the file to the storage bucket associated with your Action app.
   1. From Orchestrator Folder Path and Storage Bucket Name, choose the Orchestrator folder path and storage bucket where you want to upload the file.
   2. In the File field, input the variable where you stored the file that you downloaded file.
      For this example, input downloadFile.
   3. In the Where to upload/Path field, enter the expression downloadFile.FullName.toString to save the file in the storage bucket.
      Tip: You can store this expression in a variable.
   
   

   

   
   
4. Add an Create App Task activity, to create the action.
   1. Set the Title, and Priority accordingly.
   2. For Apps, select the Action app created earlier in the tutorial.
   3. Populate the generated fields with the appropriate variables.
   4. Under the Output section, create an UserActionData variable to store the data related to the generated action.
      In this example, name the variable as taskID.
5. Add an Assign Tasks activity to assign the task to a user within the organization.
   1. In the Task Id field, input an expression that retrieves the task ID from the output variable created at step 4, substep d.
      In this example, input the following expression: taskID.Id.Value.
   2. In the User Name or Email field input the username or the email address of the user to whom you want to assign this action.
   
   

   

   
   
6. Add a Wait for App Task and Resume activity to wait for the user to complete the action and then resume the workflow.
   1. In the Created App Task field, input the output variable created at step 4, substep d.
   2. In the Action taken field, create a variable (example: userActionTaken) to store the type of action the user took to complete the task.
7. Add a Log Message activity to print the type of action that the user took to complete the task. Use an expression such as "The action that user used to complete the Validate Invoice action was " + userActionTaken.ToString
   
   

   

   
   

Workflow example

To follow the steps and try out the tutorial yourself, download the sample Studio Desktop project here. To open it in Studio Web, save the project to Cloud, and then check your Studio Web for the project to open it there.