renai.bell@nintex.com

Nintex Workflow Cloud External Start

Blog Post created by renai.bell@nintex.com Employee on Sep 9, 2016

Greetings,

 

We’re excited to announce that the latest release includes the “External start” event within the Nintex connector. Selecting this as the start event of your workflow will provide an authenticated REST URL for the workflow. This URL returns the JSON definition of the workflow (including optional parameters derived from variables) which will start the workflow.

 

What does this allow you to do?

  • Execute a Nintex Workflow Cloud workflow from an existing Nintex Workflow product using the Web request workflow action.
  • Execute a Nintex Workflow Cloud workflow either from within the same tenant or a different tenant using the Call web service workflow action.
  • Execute a Nintex Workflow Cloud workflow from an application that will allow you to make a REST call.

 

How would you go about doing this?

1. In the Start event configuration, select the Nintex connector and select the External start event.

2. Define your Start event variables. These start event variables will become the input into your workflow when you call the workflow.

3. Configure the steps in your workflow, referencing the Start event variables in your workflow actions as needed.

4. Once the workflow is configured and published, you will get a URL that contains an authentication token which will return the workflow Swagger specification.

e.g. <tenantURL>/api/v1/workflow/published/{workflowid}/swagger.json?token={token}

5. View the Swagger definition in your browser by copying and pasting the URL. Take note of the start event variable names in the Swagger specification that you can pass values to via a REST call.

        {

            name: "API Parameters",
            required: true,
            in: "body",
            schema: {
               type: "object",
               properties: {
                  startData: {
                       type: "object",
                       properties: {
                          se_variable_11: {
                              title: "name1",
                              description: "",
                              type: "string"
                          },
                          se_variable_21: {
                              title: "name2",
                              description: "",
                              type: "string"
                          }
                       }
                  },
                  options: {
                        type: "object",
                        properties: {
                          callbackUrl: {
                             title: "callbackUrl",
                             description: "A Url to return the results back (https urls only)",
                             type: "string"
                          }
                      }
                  }
               }
            }

        }

6. In your workflow, tool, or application of choice, configure a REST call with an HTTP request of type POST to the authenticated URL. You must remove the 'swagger.json' from the URL and add 'instances' to it:

e.g. <tenantURL>/api/v1/workflow/published/{workflowid}/instances?token={token}

Your URL should look similar to:

https://nintextenant.workflowcloud.com/api/v1/workflow/published/4ab2afb5-31c0-4d7b-a04f-00ee3ad1b5c6/instances?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJOV0MiLCJ3b3JrZmxvd0lkIjoiNGFiMmFmYjUtMzFjMC00ZDdiLWEwNGYtMDBlZTNhZDFiNWM2IiwidGVuYW50SWQiOiJuaW50ZXhkZW1vIiwiaWF0IjoxNDczMzkzMjIyfQ.fyNsKK7DxylwIC3vdu8jHhNCfTJ5DUByzD0FLUB-wDk

7. In the HTTP request header, put the following:

content-type: application/json

8. In the HTTP request content/body pass the parameters as defined in the start event variables of the workflow. Optionally, you can specify a callback URL to receive all the workflow values once the workflow has completed. 

{
   "startData": {

      "se_variable_11": "valuetopassintotheworkflow",
      "se_variable_21": "valuetopassintotheworkflow "

   }

   "options": {

      "callbackURL": "https://url.to/callback"

   }

}

 

9. Your workflow can now be triggered externally!

 

We are currently working on the next iteration of this feature, which will include the ability to return values from the call. Stay tuned!

 

Our ask of you: We are still deciding whether to call this "External start". Please feel free to suggest other names in the comments. We look forward to what you might come up with!

Outcomes