IPS Workflowgroup Management API
by sanjeevgiri

IPS Workflowgroup Management API

IPS Workflowgroup Management API
models
WorkflowGroupsMetadata
Workflowgroups

Payload structure for workflow group metadata. This information is provided and seeded by connector engineering lead.

Object
integrationCode
string read-only

Integration code allocated to a specific Vertex built connector in Integration Platform (IPS)

Example:
vtxubleinv
integrationName
string read-only

Connector name used in IPS

Example:
Vertex E-Invoicing for Oracle ERP
sharedConfigGroupMetadata
ConfigGroupMetadata read-only

Information about workflowgroup parameters that are common across two or more workflowgroups

sharedConfigGroupPropertiesMetadata
Array of ConfigGroupPropertyMetadata read-only

This is for information purposes. It is expected that values defined in this list, matches the property codes seeded for the sharedConfigGroupMetadata.

groups
Array of WorkflowGroupMetadata read-only

Information about one of more workflow groups.

ConfigGroupMetadata
Workflowgroups

Information about workflow group parameters that are common across two or more workflowgroups

Object
code
string read-only

Connector team defined code of a config group. See IPS integration management and tenant integration maangement APIs for more details.

name
string read-only

Connector team defined name of a config group. See IPS integration management and tenant integration maangement APIs for more details.

description
string read-only

Config group description.

ConfigGroupPropertyMetadata
Workflowgroups

Information about a workflow group(s) input parameter

Object
code
string

Connector team defined code for a given config group property. See IPS integration management and tenant integration maangement APIs for more details.

name
string

Connector team defined name for a given config group property. See IPS integration management and tenant integration maangement APIs for more details.

description
string

Connector team defined description for a given config group property. See IPS integration management and tenant integration maangement APIs for more details.

type
string

Connector team defined type for a given config group property. See IPS integration management and tenant integration maangement APIs for more details. The type definitions for workflow parameters may have different characteristics from the generic CPS defined property types.

sensitive
boolean

Sensitive property indicator.

defaultValue
string

Connector team defined default value for a given config group property. See IPS integration management and tenant integration maangement APIs for more details.

constraints
string

Comma separated constraints information (human readable)

constraintsMetadata
string

JSON structured constraints (machine readable)

WorkflowGroupMetadata
Workflowgroups
Object
code
string read-only

Engineering team defined code for a given connector workflow group.

name
string read-only

Engineering team defined name for a given connector workflow group

description
string read-only

Engineering team defined description for a given connector workflow group

workflowGroupActions
Array of WorkflowGroupAction

Engineering team defined applicable actions for a given workflow group. This can be empty in some cases. These actions will be used to drive connector MFE submit button labels or modals.

configGroupMetadata
ConfigGroupMetadata

Engineering team defined schema for input parameters that need to be assigned/set by our customers.

configGroupPropertiesMetadata
Array of ConfigGroupPropertyMetadata

Full list of expected properties for a given workflowGroupConfigMetadata

additionalSearchPropertiesMetadata
Array of ConfigGroupPropertyMetadata

Engineering team defined search attributes for workflow executions with this group

workflows
Array of WorkflowMetadata

Engineering team assigned workflows for this group

WorkflowMetadata
Workflowgroups
Object
code
string

Engineering team defined code for a given connector workflow (This is the value used when communicating with underlying workflow engine)

name
string

Engineering team defined name for a given connector workflow

description
string

Engineering team defined description for a given connector workflow

namespace
string

Engineering team provisioned namespace where this workflow is expected to executed

taskQueueName
string

Engineering team defined name for task queue where workflow execution requests will be published (on demand or scheduled)

readonly
boolean

Workflows with this flag turned cannot be triggered/scheduled. These are typically child workflows that are spawned from triggerable workflows and cannot be executed independently.

schedulable
boolean

Enabled for workflows that are expected to be executed periodically

customerDefinedInputPropertyCodes
Array of string

Properties that requires user input. These must be a subset of properties defined in WorkflowGroupsMetadata.sharedConfigGroupPropertiesMetadata[].code + WorkflowGroupMetadata.configGroupPropertiesMetadata[].code. Engineering teams can define and seed constraints for this property.

customerDefinedScheduleAtMinutePropertyCode
string

This parameter is only applicable for workflows with schedulable flag turned on. These must be a subset of properties defined in WorkflowGroupsMetadata.sharedConfigGroupPropertiesMetadata[].code + WorkflowGroupMetadata.configGroupPropertiesMetadata[].code. User provided value is expected to be an integer value between 0 and 59.

customerDefinedScheduleAtHourPropertyCode
string

This parameter is only applicable for workflows with schedulable flag turned on. These must be a subset of properties defined in WorkflowGroupsMetadata.sharedConfigGroupPropertiesMetadata[].code + WorkflowGroupMetadata.configGroupPropertiesMetadata[].code. User provided value is expected to be an integer value between 0 and 23.

customerDefinedScheduleOnDayOfWeekPropertyCode
string

This parameter is only applicable for workflows with schedulable flag turned on. These must be a subset of properties defined in WorkflowGroupsMetadata.sharedConfigGroupPropertiesMetadata[].code + WorkflowGroupMetadata.configGroupPropertiesMetadata[].code. User provided value is expected to be an integer value between 1 and 7.

applicationDefinedWorkflowInputPropertiesMetadata
Array of ConfigGroupPropertyMetadata

Arbitrary properties used for workflow input object attributes using default values specified by connector engineering

show more
WorkflowGroupAction
Workflowgroups

Note: Scheduling or unscheduling a scheduled workflow that is shared across connector applications will currently impact other applications. This is specifically applicable to shared einvoice polling jobs. This will eventually be addressed when we get push notifications.

string
Enumeration:
TRIGGER

This action save user defined input parameters and trigger all workflows in a group. It will also schedule scheduled workflows using default or user provided intervals.

SCHEDULE

This action save user defined input parameters and schedule scheduled workflows using default or user provided intervals.

UNSCHEDULE

This action save user defined input parameters and unschedule scheduled workflows using default or user provided intervals. Unscheduled workflows in a given group is expected to be skipped.

WorkflowExecution
Workflowgroups
Object
id
string

Workflow execution id

code
string

Workflow code (engineering defined)

status
string

Workflow status

startedAt
string date-time

Time when a given unit of work was published to task queue

endedAt
string date-time

Time when a given unit of work was consumed from task queue and ended (graceful or forced)

input
string

Workflow execution input. Sensitive data must be masked.

output
string

Workflow execution outcome. Sensitive data must be masked.

WorkflowGroupExecutionStartRequest
Workflowgroups
Object
code
string

Engineering team defined code for a given connector workflow group. (See WorkflowGroupMetadata). Application must reject codes that are not defined in the WorkflowGroupsMetadata.group[*].code

action
WorkflowGroupAction

One of engineering team defined action for a given connector workflow group. (See WorkflowGroupMetadata). Unsupported (actions that are not defined in WorkflowGroupMetadata.actions) actions will be rejected.

configProperties
Object

Map of key value pair where all keys must be a subset of WorkflowGroupMetadata.configGroupPropertiesMetadata[].code and WorkflowGroupsMetadata.sharedConfigGroupProperties[].code

additional properties
string
WorkflowGroupExecutionStartResponse
Workflowgroups
Object
workflows
Array
Object
code
string

Workflow code

output
string

Execution output

WorflowGroupExecutionSearchRequest
Workflowgroups
Object
statuses
Array of WorkflowExecutionStatus

Filter by one or more workflow execution statuses

workflowCodes
Array of string

This values must be a subset of codes defined in WorkflowGroupMetadata.workflows[*].code

startedAt
string date-time
endedAt
string date-time
additionalSearchProperties
Object

Map of key value pair where all keys must be a subset of WorkflowGroupMetadata.additionalSearchPropertiesMetadata[].code

additional properties
string
WorkflowGroupExecutionSearchResponse
Workflowgroups
Object
content
Array of WorkflowExecution
WorkflowExecutionStatus
Workflowgroups
string
Enumeration:
RUNNING
COMPLETED
TIMEDOUT
FAILED
CONTINUED_AS_NEW
CANCELLED
TERMINATED
pagination
page
integer optional

Page number. (Starts from 0)

Default:
0
size
string optional

Requested number of elements in a given page or results

Min length: 1
Max length: 100
Default:
20
sort
string optional

Multi value sort parameter used for paging across a large data set. The expected format is as follows when specified:

sortField,sortOrder

sortField can be any arbitrary field specific to the content that is being paged sortOrder is ASC or DESC. The sort order defaults to ASC when left unspecified.

A page can be sorted using multiple columns by providing multiple sort query parameters

pageSort=field1,ASC&pageSort=field2,DESC

Currently the only value supported is publishedAt timestamp value that is internally created during processing. Other values will either be ignored or will potentially result in error.

operations
Get workflow group metadata
GET /integrationcodes/{integrationCode}/workflowgroupsmetadata
Execute workflowgroup
POST /tenantintegrations/{entitlementId}/workflowgroups
Search workflowgroup executions
GET /tenantintegrations/{entitlementId}/workflowgroups/{workflowGroupCode}
Get workflow group metadata
Workflowgroups
GET /integrationcodes/{integrationCode}/workflowgroupsmetadata

Authentication

OAuth2

This endpoint responds with workflow groups associated with a specific connector (entitlement.integration). The information in the response payloads provides information about various applicable workflows, their groupings, input parameters, and constraints.

Path variables

integrationCode
string required

Responses

200 OK

Sample application defined metadata for Oracle E-Invoicing connector

Body
WorkflowGroupsMetadata
Example 1
GET https://integration-platform-services-dev.platdev.vtxdev.net/tiwfg/v1/tenantintegrations/{entitlementId}/workflowgroupsmetadata HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
  "integrationCode": "vtxubleinv",
  "integrationName": "Vertex E-Invoicing for Oracle ERP",
  "sharedConfigGroupMetadata": {
    "code": "workflowGroupsSettings",
    "name": "Vertex E-Invoicing for Oracle ERP: General workflow groups settings",
    "description": "Vertex E-Invoicing for Oracle ERP: General workflow groups settings"
  },
  "sharedConfigGroupPropertiesMetadata": [
    {
      "code": "eInvoicingApiClientId",
      "name": "E-Invoicing API Client Id",
      "description": "Tenant specific e-invoicing m2m client id",
      "type": "STRING",
      "sensitive": true,
      "defaultValue": "",
      "constraints": "required",
      "constraintsMetadata": "[{\"required\": true}]"
    },
    {
      "code": "eInvoicingApiClientSecret",
      "name": "E-Invoicing API Client Secret",
      "description": "Tenant specific e-invoicing m2m client secret",
      "type": "STRING",
      "sensitive": true,
      "defaultValue": "",
      "constraints": "required",
      "constraintsMetadata": "[{\"required\": true}]"
    }
  ],
  "groups": [
    {
      "code": "oracleErpEinvoicingOutbound",
      "name": "E-Invoicing Outbound Status Workflows",
      "description": "E-Invoicing Outbound Status Workflows",
      "workflowGroupActions": [
        "TRIGGER",
        "SCHEDULE",
        "UNSCHEDULE"
      ],
      "configGroupMetadata": {
        "code": "oracleErpEinvoicingOutbound",
        "name": "E-Invoicing Outbound Status Workflows",
        "description": "IPS config group for describing customer defined values outbound e-invoicing status workflows"
      },
      "configGroupPropertiesMetadata": [
        {
          "code": "outboundEInvoiceWorkflowScheduleAtMinute",
          "name": "Outbound E Invoice Schedule At Minute",
          "type": "NUMBER",
          "defaultValue": "15",
          "constraintsMetadata": "[\"type\": \"number\",\"required\":true, \"min\": 15, \"max\": 59,]"
        },
        {
          "code": "outboundEInvoiceWorkflowScheduleAtHour",
          "name": "Outbound E Invoice Schedule At Hour",
          "type": "NUMBER",
          "constraintsMetadata": "[\"type\": \"number\",\"required\":true, \"min\": 0, \"max\": 23,]"
        },
        {
          "code": "outboundEInvoiceWorkflowScheduleOnDayOfWeek",
          "name": "Outbound E Invoice Schedule On Day of Week",
          "type": "NUMBER",
          "constraintsMetadata": "[\"type\": \"number\",\"required\":true, \"min\": 1 \"max\": 7,]"
        }
      ],
      "additionalSearchPropertiesMetadata": [
        {
          "code": "documentId",
          "name": "Document ID",
          "description": "Vertex e-invoicing generated document id",
          "type": "STRING"
        }
      ],
      "workflows": [
        {
          "code": "EventTypeWebhookSubscription",
          "name": "Event type webhook subscription",
          "description": "Subscribe for EINVOICE_RECEIVED event",
          "namespace": "einvoicing-connector",
          "taskQueueName": "eventTypeWebhookSubscription",
          "applicationDefinedWorkflowInputPropertiesMetadata": [
            {
              "code": "einvoiceEventType",
              "name": "E-Invoice event type",
              "description": "E-Invoice event type for outbound status notifications",
              "type": "STRING",
              "defaultValue": "EINVOICE_RECEIVED"
            },
            {
              "code": "callbackUrl",
              "name": "Callback URL",
              "description": "Oracle ERP E-Invoicing connector's endpoint for receiving events",
              "type": "STRING",
              "defaultValue": "https://ubleinv.cst-stage.vtxdev.net/connector-ubleinv/api/erp/invoicestatus?env=stage"
            }
          ]
        },
        {
          "code": "EinvoicingClientRegistration",
          "name": "E-Invoicing Client Registration",
          "description": "Register e-invoicing client credentials",
          "namespace": "einvoicing-connector",
          "taskQueueName": "einvoicingClientRegistration",
          "customerDefinedInputPropertyCodes": [
            "einvoiceApiClientId",
            "einvoiceApiClientSecret"
          ]
        },
        {
          "code": "OutboundEInvoiceWorkflow",
          "name": "Outbound E-Invoice Workflow",
          "description": "Outbound E-Invoice Workflow",
          "namespace": "einvoicing-connector",
          "taskQueueName": "outboundEInvoicePollingTaskQueue",
          "schedulable": true,
          "customerDefinedScheduleAtMinutePropertyCode": "outboundEInvoiceWorkflowScheduleAtMinute",
          "customerDefinedScheduleAtHourPropertyCode": "outboundEInvoiceWorkflowScheduleAtHour",
          "customerDefinedScheduleOnDayOfWeekPropertyCode": "outboundEInvoiceWorkflowScheduleOnDayOfWeek"
        },
        {
          "code": "RetrieveEInvoiceArtifactsWorkflow",
          "name": "Process einvoice notification",
          "namespace": "einvoicing-connector",
          "taskQueueName": "retrieveEInvoiceArtifactsTaskQueue",
          "schedulable": false,
          "readOnly": true
        }
      ]
    },
    {
      "code": "oracleErpEinvoicingInbound",
      "name": "E-Invoicing Inbound Workflows",
      "description": "E-Invoicing Inbound Workflows",
      "workflowGroupActions": [
        "TRIGGER",
        "SCHEDULE",
        "UNSCHEDULE"
      ],
      "configGroupMetadata": {
        "code": "oracleErpEinvoicingInbound",
        "name": "E-Invoicing Inbound Workflows",
        "description": "IPS config group for describing customer defined values for inbound e-invoicing workflows"
      },
      "configGroupPropertiesMetadata": [
        {
          "code": "inboundEInvoiceWorkflowScheduleAtMinute",
          "name": "Inbound E Invoice Schedule At Minute",
          "type": "NUMBER",
          "defaultValue": "15",
          "constraintsMetadata": "[\"type\": \"number\",\"required\":true, \"min\": 15, \"max\": 59,]"
        },
        {
          "code": "inboundEInvoiceWorkflowScheduleAtHour",
          "name": "Inbound E Invoice Schedule At Hour",
          "type": "NUMBER",
          "constraintsMetadata": "[\"type\": \"number\",\"required\":true, \"min\": 0, \"max\": 23,]"
        },
        {
          "code": "inboundEInvoiceWorkflowScheduleOnDayOfWeek",
          "name": "Inbound E Invoice Schedule On Day of Week",
          "type": "NUMBER",
          "constraintsMetadata": "[\"type\": \"number\",\"required\":true, \"min\": 1 \"max\": 7,]"
        }
      ],
      "additionalSearchPropertiesMetadata": [
        {
          "code": "documentId",
          "name": "Document ID",
          "description": "Vertex e-invoicing generated document id",
          "type": "STRING"
        }
      ],
      "workflows": [
        {
          "code": "EventTypeWebhookSubscription",
          "name": "Event type webhook subscription",
          "description": "Subscribe for EINVOICE_RECEIVED event",
          "namespace": "einvoicing-connector",
          "taskQueueName": "eventTypeWebhookSubscription",
          "applicationDefinedWorkflowInputPropertiesMetadata": [
            {
              "code": "einvoiceEventType",
              "name": "E-Invoice event type",
              "description": "E-Invoice event type for inbound status notifications",
              "type": "STRING",
              "defaultValue": "EINVOICE_RECEIVED"
            },
            {
              "code": "callbackUrl",
              "name": "Callback URL",
              "description": "Oracle ERP E-Invoicing connector's endpoint for receiving events",
              "type": "STRING",
              "defaultValue": "https://ubleinv.cst-stage.vtxdev.net/connector-ubleinv/api/erp/invoicestatus?env=stage"
            }
          ]
        },
        {
          "code": "EinvoicingClientRegistration",
          "name": "E-Invoicing Client Registration",
          "description": "Register e-invoicing client credentials",
          "namespace": "einvoicing-connector",
          "taskQueueName": "einvoicingClientRegistration",
          "customerDefinedInputPropertyCodes": [
            "einvoiceApiClientId",
            "einvoiceApiClientSecret"
          ]
        },
        {
          "code": "InboundEInvoiceWorkflow",
          "name": "Inbound E-Invoice Workflow",
          "description": "Inbound E-Invoice Workflow",
          "namespace": "einvoicing-connector",
          "taskQueueName": "inboundEInvoicePollingTaskQueue",
          "schedulable": true,
          "customerDefinedScheduleAtMinutePropertyCode": "inboundEInvoiceWorkflowScheduleAtMinute",
          "customerDefinedScheduleAtHourPropertyCode": "inboundEInvoiceWorkflowScheduleAtHour",
          "customerDefinedScheduleOnDayOfWeekPropertyCode": "inboundEInvoiceWorkflowScheduleOnDayOfWeek"
        },
        {
          "code": "RetrieveEInvoiceArtifactsWorkflow",
          "name": "Process einvoice notification",
          "namespace": "einvoicing-connector",
          "taskQueueName": "retrieveEInvoiceArtifactsTaskQueue",
          "schedulable": false,
          "readOnly": true
        }
      ]
    }
  ]
}
show more
Execute workflowgroup
Workflowgroups
POST /tenantintegrations/{entitlementId}/workflowgroups

Authentication

OAuth2

This endpoint is responsible for executing workflows associated with a given workflow group. See example for how it would look like for Oracle e invoicing connector.

  • All workflows in the group are executed senquentially and synchronosly (if action is TRIGGER and it is not marked as readonly).
  • Failure in any workflow execution is treated as a failure.
  • If a workflow is marked as readonly or workflow action is UNSCHEDULE, it will be skipped.
  • If a workflow is marked as schedulable, a schedule will be created based on the schedule parameters.

Path variables

entitlementId
string required

Request body

WorkflowGroupExecutionStartRequest

Responses

200 OK
Body
WorkflowGroupExecutionStartResponse
Example 1
Example 2

Sample execution of outbound Oracle e-invoice workflowflow groups

POST https://integration-platform-services-dev.platdev.vtxdev.net/tiwfg/v1/tenantintegrations/{entitlementId}/workflowgroups HTTP/1.1 

Content-Type: application/json;charset=UTF-8

{
    "code": "oracleErpEinvoicingOutbound",
    "action": "TRIGGER",
    "configProperties": {
        "eInvoicingApiClientId": "xxx",
        "eInvoicingApiClientSecret": "xxx",
        "outboundEInvoiceWorkflowScheduleAtMinute": "30",
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "workflows": [
        {
            "code": "EventTypeWebhookSubscription",
            "output": "success"
        },
        {
            "code": "EinvoicingClientRegistration",
            "output": "success"
        },
        {
            "code": "OutboundEInvoiceWorkflow"
            "output": "records fetched 11, initiated downstream process"
        }
        
    ]
}
show more

Sample execution of inbound Oracle e-invoice workflowflow groups

POST https://integration-platform-services-dev.platdev.vtxdev.net/tiwfg/v1/tenantintegrations/{entitlementId}/workflowgroups HTTP/1.1 

Content-Type: application/json;charset=UTF-8

{
    "code": "oracleErpEinvoicingInbound",
    "action": "TRIGGER",
    "configProperties": {
        "eInvoicingApiClientId": "xxx",
        "eInvoicingApiClientSecret": "xxx",
        "inboundEInvoiceWorkflowScheduleAtMinute": "30",
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "workflows": [
        {
            "code": "EventTypeWebhookSubscription",
            "output": "success"
        },
        {
            "code": "EinvoicingClientRegistration",
            "output": "success"
        },
        {
            "code": "OutboundEInvoiceWorkflow"
            "output": "records fetched 11, initiated downstream process"
        }
        
    ]
}
show more
Search workflowgroup executions
Workflowgroups
GET /tenantintegrations/{entitlementId}/workflowgroups/{workflowGroupCode}

Authentication

OAuth2

For pagination, sorting is based on execution start time, and sort order is always descending.

Path variables

entitlementId
string required
workflowGroupCode
string required

Request parameters

page
integer optional

Page number. (Starts from 0)

Default:
0
size
string optional

Requested number of elements in a given page or results

Min length: 1
Max length: 100
Default:
20

Request body

WorflowGroupExecutionSearchRequest

Responses

200 OK
Body
WorkflowGroupExecutionSearchResponse
Example 1
Example 2

Example response for search Oracle einvoicing outbound workflow group

GET https://integration-platform-services-dev.platdev.vtxdev.net/tiwfg/v1/tenantintegrations/3b5ca703-a21a-452f-af8e-aec95539f5aa/workflowgroups/oracleErpEinvoicingOutbound HTTP/1.1 

Content-Type: application/json;charset=UTF-8

{
    "statuses": [
        "COMPLETED", "FAILED"
    ],
    "workflowCodes": [
        "RetrieveEInvoiceArtifactsWorkflow"
    ],
    "startedAt": "2025-05-23T00:00:00.000Z",
    "endedAt": "2025-05-23T01:00:00.000Z",
    "additionalSearchProperties": {
        "documentId": "28ae361a-2e26-4182-b79e-a4e375435b23"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "f6117d7b-a3b7-4d34-9bca-b9d6f1a41a80",
            "code": "RetrieveEInvoiceArtifactsWorkflow",
            "status": "COMPLETED",
            "startedAt": "2025-05-23T00:01:00.000Z",
            "endedAt": "2025-05-23T00:02:00.000Z",
            "input": "28ae361a-2e26-4182-b79e-a4e375435b23",
            "output": "Successfully transmitted to callback endpoint"
        }
    ]
}
show more

Example response for search Oracle einvoicing outbound workflow group

GET https://integration-platform-services-dev.platdev.vtxdev.net/tiwfg/v1/tenantintegrations/3b5ca703-a21a-452f-af8e-aec95539f5aa/workflowgroups/oracleErpEinvoicingInbound HTTP/1.1 

Content-Type: application/json;charset=UTF-8

{
    "statuses": [
        "COMPLETED", "FAILED"
    ],
    "workflowCodes": [
        "RetrieveEInvoiceArtifactsWorkflow"
    ],
    "startedAt": "2025-05-23T00:00:00.000Z",
    "endedAt": "2025-05-23T01:00:00.000Z",
    "additionalSearchProperties": {
        "documentId": "28ae361a-2e26-4182-b79e-a4e375435b23"
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "f6117d7b-a3b7-4d34-9bca-b9d6f1a41a80",
            "code": "RetrieveEInvoiceArtifactsWorkflow",
            "status": "COMPLETED",
            "startedAt": "2025-05-23T00:01:00.000Z",
            "endedAt": "2025-05-23T00:02:00.000Z",
            "input": "28ae361a-2e26-4182-b79e-a4e375435b23",
            "output": "Successfully transmitted to callback endpoint"
        }
    ]
}
show more