cancel
Showing results for 
Search instead for 
Did you mean: 

Starting a Component Workflow via API endpoint service or application

Topic

How to start a Component Workflow via a HTTPS API endpoint capable service or application.

 


Instructions

You can start a component workflow using HTTPS-capable application, by sending an HTTPS Post request, the external application that starts the Component Workflow must provide the start variables defined by the Component workflow.

Component workflows enable you to

  • Reuse and share workflows.
  • Hide technical complexity e.g. web services.
  • Separate processes for security reasons.
  • Implement consistency e.g. for approval processes.

You can start your Component workflow from any service or application that can:

  • Make POST calls to HTTPS endpoints.

  • Send a request payload in the body with a content-type of application/JSON.


To Start your Component workflow from another service or application
  1. Configure your application to make a POST request to the Component workflow URL.
Component workflows are built at the Site Workflow level. First navigate to Site Contents To access the Site Workflow Gallery:

a. To the right of a workflow in the list click ...
b. Click {.} API endpoints.
c. In the Component dialog box, to the right of URL with token, click COPY.

        2. Configure your application to submit a JSON request body with the start variables.
a. To the right of a workflow in the list click ...
b. Click {.} API endpoints.
c. In the Component dialog box, to the right of URL with token, click COPY.
 
        3. If you want the Component workflow to call another endpoint when the workflow completes, configure the callbackURL field in the request payload.
All callback URLs are sent as HTTPS POST.
 
 
Example of a request body:
This request includes two start variables (first name and last name) and a callback URL.

{
  "startData": {
    "se_firstname_11": "John",
    "se_secondname_21": "Smith",
  },
  "options": {
    "callbackUrl": "https://callbackurl.com"
  }
}

 
Example of a callback post body:
This request includes two start variables (first name and last name) and a callback URL.

{
  "startData": {
    "se_firstname_11": "John",
    "se_secondname_21": "Smith",
  },
  "options": {
    "callbackUrl": "https://callbackurl.com"
  }
}

 

Note: 
• If your application or service can consume OpenAPI Specifications, you can import the specification of the Component workflow using the OpenAPI Specification URL.

• You can make 30 calls per 60 seconds to all Component workflows across a tenant.

• The Component workflow endpoint returns only the workflow ID of the called workflow. If you want to retrieve data from the completed workflow, you must accept it via a    callback URL.

 

Additional Information

Endpoints and responses

The base URL of all Component workflow endpoints is the same:

https://{tenancyName}.sharepoint.com/api/v1/componentworkflows/{componentWorkflowId}

Where:

https://acme.sharepoint.com

  • {tenancyName} is the name of your tenancy, for example acme

  • {workflowID} is the unique identifier of the Component workflow.

Note: 
Each API call must include the authentication token:
https://{tenancyname}.nintex.com/api/v1/componentworkflows/{componentWorkflowId}?api-key={token}


 

/Start
Create and start a workflow instance. If an instance token for a paused instance is supplied, start that paused instance.

Payload:

JSON object in request body containing:

  • Metadata
  • Start event type
  • Start data
  • Callback URL
Response:Workflow ID of the started workflow.

Note: 
The Component workflow endpoint returns only the workflow ID of the called workflow. If you want to retrieve data from the completed workflow, you must include a callback URL in the request payload.


HTTPS responses
HTTPS status codeDescription
202Accepted
400Bad Request
404Not Found
500Internal Server Error
503Service Unavailable

 

Related Links


Labels: (2)
Version history
Revision #:
38 of 42
Last update:
‎06-13-2019 06:00 PM
Updated by: