Edit this page on GitHub

Home > docs > api > Process

Process

A process is an execution of a flow in repository of a project.

The REST API provides support for a number of operations:

Start a Process

The best approach to start a process manually is to execute a flow defined in the Concord file in a repository of an existing project using the Concord Console.

Alternatively you can create a ZIP file with the necessary content and submit it for execution.

For simple user interaction with flows that include forms, a process can also be started in a browser directly and therefore via a link e.g. in an email or online documentation or even any web applicaion.

Following is the full information about the API. It allows the user to starts a new process using the provided files as request data. Accepts multiple additional files, which are put into the process’ working directory.

  • URI /api/v1/process
  • Method POST
  • Headers Authorization, Content-Type: multipart/form-data
  • Body Multipart binary data.

    The values will be interpreted depending on their name:

    • activeProfiles - a comma-separated list of profiles to use;
    • archive - ZIP archive, will be extracted into the process’ working directory;
    • request - JSON file, will be used as the process’ parameters (see examples below);
    • any value of application/octet-stream type - will be copied as a file into the process’ working directory;
    • orgId or org - ID or name of the organization which “owns” the process;
    • projectId or project - ID or name of the project which will be used to run the process;
    • repoId or repo - ID or name of the repository which will be used to run the process;
    • repoBranchOrTag - overrides the configured branch or tag name of the project’s repository;
    • repoCommitId - overrides the configured GIT commit ID of the project’s repository;
    • entryPoint - name of the starting flow;
    • out - list of comma-separated names of variables that will be saved after the process finishes. Such variables can be retrieved later using the status request;
    • startAt - ISO-8601 date-time value. If specified, the process will be scheduled to run on the specified date and time. Can’t be in the past. Time offset (e.g. Z, -06:00) is required;
    • any other value of text/plain type - will be used as a process’ parameter. Nested values can be specified using . as the delimiter;
    • any other value will be saved as a file in the process’ working directory.
  • Success response
      Content-Type: application/json
    
      {
        "instanceId" : "0c8fdeca-5158-4781-ac58-97e34b9a70ee",
        "ok" : true
      }
    

Examples

An example of a invocation triggers the default flow in the default repository of myProject in the myOrg organization without further parameters.

curl -i -F org=myOrg -F project=myProject -F repo=default https://concord.example.com/api/v1/process

(use -i or -v to see the server’s reply in case of any errors).

You can specify the flow e.g. main to start with a different flow for the same default repository of the myProject without further parameters.

curl ... -F entryPoint=main https://concord.example.com/api/v1/process

Passing arguments:

curl ... -F arguments.x=123 https://concord.example.com/api/v1/process

Note that all arguments passed this way are String values. If you wish to pass other types of values you can use JSON files:

curl ... -F request=@values.json https://concord.example.com/api/v1/process

or using Curl’s inline syntax:

curl ... -F request='{"arguments": {"x": true}};type=application/octet-stream' https://concord.example.com/api/v1/process

Scheduling an execution:

curl ... -F startAt='2018-03-15T15:25:00-05:00' https://concord.example.com/api/v1/process

You can also upload and run a concord.yml file without creating a Git repository or a payload archive:

curl ... -F concord.yml=@concord.yml https://concord.example.com/api/v1/process

Form Data

Concord accepts multipart/form-data requests to start a process. Special variables such as arguments, archive, out, activeProfiles, etc are automatically configured. Other submitted data of format text/plain is used to configure variables. All other information is stored as a file in the process’ working directory.

However, if user tries to upload a .txt file

curl ... -F myFile.txt=@myFile.txt -F archive=@target/payload.zip \ 
  https://concord.example.com/api/v1/process

then curl uses Content-Type: text/plain header and Concord stores this as a configuration variable instead of a file as desired.

As a workaround you can specify the content type of the field explicitly:

curl ... \
-F "myFile.txt=@myFile.txt;type=application/octet-stream" \
-F archive=@target/payload.zip \
https://concord.example.com//api/v1/process

ZIP File

If no project exists in Concord, a ZIP file with flow definition and related resources can be submitted to Concord for execution. Typically this is only suggested for development processes and testing or one-off process executions.

Follow these steps:

Create a zip archive e.g. named archive.zip containing the Concord file - a single concord.yml file in the root of the archive:

flows:
  default:
  - log: "Hello Concord User"

The format is described in Directory Structure document.

Now you can submit the archive directly to the Process REST endpoint of Concord with the admin authorization or your user credentials as described in our getting started example:

curl -F archive=@archive.zip http://concord.example.com/api/v1/process

The response should look like:

{
  "instanceId" : "a5bcd5ae-c064-4e5e-ac0c-3c3d061e1f97",
  "ok" : true
}

You can start a new process in Concord via simply accessing a URL in a browser.

Clicking on the link forces the users to log into the Concord Console, and then starts the process with the specified parameter. Progress is indicated in the user interface showing the process ID and the initiator. After completion a link to the process is displayed, so the user can get more information. If a form is used in the flow, the progress view is replaced with the form and further steps can include additional forms, which also show up in the browser.

  • URI /api/v1/org/{orgName}/project/{projectName}/repo/{repoName}/start/{entryPoint}
  • Method GET
  • Headers none
  • Required Parameters
    • orgName - name of the organization in Concord
    • projectName - name of the project in Concord
    • repoName - name of the repository in the project
    • entryPoint - name of the entryPoint to use
  • Optional Parameters
    • activeProfiles - comma separate list of profiles to activate
    • arguments - process arguments can be supplied using the arguments. prefix
  • Body none
  • Success response Redirects a user to a form or an intermediate page or a results page that allows access to the process log.
  • Examples
    • Minimal: /api/v1/org/Default/project/test-project/repo/test-repo/start/default
    • Different flow main: /api/v1/org/Default/project/test-project/repo/test-repo/start/main
    • Specific profile: /api/v1/org/Default/project/test-project/repo/test-repo/start/default?activeProfiles=dev
    • Passing process arguments: /api/v1/org/Default/project/test-project/repo/test-repo/start/default?arguments.x=123&arguments.y=boo

Stop a Process

Forcefully stops the process.

  • URI /api/v1/process/${instanceId}
  • Method DELETE
  • Headers Authorization
  • Parameters ID of a process: ${instanceId}
  • Body none
  • Success response Empty body.

Getting the Status of a Process

Returns the current status of a process.

Note: this is a v2 endpoint.

  • URI /api/v2/process/${instanceId}
  • Method GET
  • Headers Authorization
  • Parameters ID of a process: ${instanceId}
  • Query parameters
    • include: additional entries to return (checkpoints, childrenIds, history), repeat the parameter to include multiple additional entries;
  • Body none
  • Success response
      Content-Type: application/json
    
      {
        "instanceId" : "45beb7c7-6aa2-40e4-ba1d-488f78700ab7",
        "parentInstanceId" : "b82bb6c7-f184-405e-ae08-68b62125c8be",
        "projectName" : "myProject2",
        "createdAt" : "2017-07-19T16:31:39.331+0000",
        "initiator" : "admin",
        "lastUpdatedAt" : "2017-07-19T16:31:40.493+0000",
        "status" : "FAILED",
        "childrenIds":["d4892eab-f75d-43a2-bb26-20903ffa10d8","be79ee81-78db-4afa-b207-d361a417e892","d5a35c8f-faba-4b9d-b957-ca9c31bf2a39"]
      }
    

Retrieve a Process Log

Downloads the log file of a process.

  • URI /api/v1/process/${instanceId}/log
  • Method GET
  • Headers Authorization, Range
  • Parameters ID of a process: ${instanceId}
  • Body
      Content-Type: text/plain
    

    The log file.

  • Success response Redirects a user to a form or an intermediate page.

  • Example
      curl -H "Authorization: ..." -H "Range: ${startByte}-${endByte}"\
      http://concord.example.com/api/v1/process/${instanceId}/log
    

Downloading an Attachment

Downloads a process’ attachment.

  • URI /api/v1/process/${instanceId}/attachment/${attachmentName}
  • Method POST
  • Headers Authorization, Content-Type: application/octet-stream
  • Body none
  • Success response
      Content-Type: application/octet-stream
    
      ...data...
    

List Processes

Retrieve a list of processes.

Note: this is a v2 endpoint.

  • URI /api/v2/process
  • Query parameters
    • orgId: filter by the organization’s ID;
    • orgName: filter by the organization’s name;
    • projectId: filter by the project’s ID;
    • projectName: filter by the project’s name, requires orgId or orgName;
    • afterCreatedAt: limit by date, ISO-8601 string with time offset;
    • beforeCreatedAt: limit by date, ISO-8601 string with time offset;
    • tags: filter by a tag, repeat the parameter to filter by multiple tags;
    • status: filter by the process status;
    • initiator: filter by the initiator’s username (starts with the specified string);
    • parentInstanceId: filter by the parent’s process ID;
    • include: additional entries to return (checkpoints, childrenIds, history), repeat the parameter to include multiple additional entries;
    • limit: maximum number of records to return;
    • offset: starting index from which to return;
    • meta.[paramName][.operation]: filter by the process metadata’s value paramName using the specified comparison operation. Supported operations:
      • eq, notEq - equality check;
      • contains, notContains - substring search;
      • startsWith, notStartsWith - beginning of the string match;
      • endsWith, notEndsWith - end of the string match. If the operator is omitted, the default contains mode is used. Metadata filters require projectId or orgName and projectName to be specified.
  • Method GET
  • Body none
  • Success response
      Content-Type: application/json
    
      [
        { "instanceId": "...", "status": "...", ... },
        { "instanceId": "...", ... }
      ]
    
  • Example
    curl -H "Authorization: ..." \
    'http://concord.example.com/api/v2/process?orgName=myOrg&projectName=myProject&meta.myMetaVar.startsWith=Hello&afterCreatedAt=2020-08-12T00:00:00.000Z'
    

Count Processes

Returns a total number of processes using the specified filters.

Note: this is a v2 endpoint.

  • URI /api/v2/process/count
  • Query parameters Same as the list method. A projectId or a combination of orgName and projectName is required. Not supported: limit, offset, include.
  • Method GET
  • Body none
  • Success response
      Content-Type: application/json
    
      12
    

Resume a Process

Resume a previously SUSPENDED process.

Note: usually Concord suspends and resumes processes automatically, e.g. when forms or suspendable tasks used. The resume API can be used for custom integrations or for special use cases.

  • URI /api/v1/process/${instanceId}/resume/${eventName}
  • Method POST
  • Headers Authorization, Content-Type: application/json
  • Parameters ID of a process: ${instanceId} Event name: ${eventName} - must match the event name created when the process was suspended.
  • Body a JSON object. Must match the process configuration format:
      {
        "arguments": {
            "x": 123
        }
      }
    
  • Success response
      Content-Type: application/json
    
      {
        "ok": true
      }
    

Process Events

List Events

Retrieve a list of events.

  • URI /api/v1/process/${instanceId}/event
  • Parameters ID of a process: ${instanceId}
  • Query parameters
    • type: event type;
    • after: limit by date, ISO-8601 string with time offset;
    • eventCorrelationId: correlation ID of the event (e.g. a task call);
    • eventPhase: for multi-phase events (e.g. a task call - PRE or POST);
    • includeAll: if true additional, potentially sensitive, data is returned (e.g. task call parameters);
    • limit: maximum number of records to return.
  • Method GET
  • Body none
  • Success response
      Content-Type: application/json
    
      [
        {
          "id" : "eba7360e-790a-11e9-a33e-fa163e7ef419",
          "eventType" : "PROCESS_STATUS",
          "data" : {"status": "PREPARING"},
          "eventDate" : "2019-05-18T01:19:02.172Z"
        }, {
          "id" : "ebfabd24-790a-11e9-a33e-fa163e7ef419",
          "eventType" : "PROCESS_STATUS",
          "data" : {"status": "ENQUEUED"},
          "eventDate" : "2019-05-18T01:19:02.720Z"
        }
      ]