Information model and API

Overview

The Process domain mainly consists of the following four objects:

• Activity
• Workflow Definition
• Workflow Instance
• Change Request

Activity

An activity is an atomic building block that represents a single executable step on workflow. Activities can be grouped by their type, following are mentioned some of the common activity types

Console

Read Line: Read text from console
Write Line: Write text to the console

HTTP

Send HTTP request: Send an HTTP request
HTTP endpoint: Handle incoming HTTP request
Redirect: Write an HTTP redirect response

Control Flow

If/Else: Evaluate a Boolean expression and continue execution depending on the result
For loop: Iterate between two numbers
For Each loop: Iterate over a collection
Parallel For Each: Iterate over a collection in parallel
While: Execute while a given condition is true
Break: Break out of a While, For or ForEach loop
Fork: For workflow execution into multiple branches
Join: Merge workflow execution back into a single branch
Switch: Evaluate multiple conditions and continue execution depending on the results

Email

Send email: Send an email message

File

Delete file: Deletes file at specified location
File exists: Checks if a file exists
Read file: Read file content
Enumerate files: Enumerate over files in a given folder
Out file: Output input value to specified location
Temp file: Create a temporary file and return its path

Primitives

Fault: Put workflow in a faulted state
Set name: Set the name of workflow instance
Set variable: Set variable on workflow

Scripting

Run JavaScript: Run JavaScript code

Timers

Cron: Triggers periodically based on a specified cron expression
Timer: Triggers at a specified interval
Start at:: Triggers at a specified moment in time

For more information on Elsa specific activities and functionality please take a look at Elsa’s documentation: https://elsa-workflows.github.io/elsa-core/docs/installation/installing-elsa-core

AIH Specific Activities

Send HTTP Request to AIH: This activity is designed to send http request to any AIH endpoint
Send Form HTTP Request to AIH: This activity is designed to send http request to AIH endpoint which has a request type of “multipart/form-data”
AIH event received: Activity is triggered when an event is received from AIH, can be used as the starting point of workflow
Execute commands and queries in Process module: This activity can access commands and queries of Process module. Since both workflows and change requests are in Process module there is no need for workflow to communicate with itself through HTTP calls
Run job in Data Processing API: Can be used to run a job in DataProcessing API, user should provide configuration Id and run options
Build html: This activity is designed to translate liquid code with html to plain html. The activity has one input, which is the liquid html. The output of the activity is the html result

Activity related endpoints:

 

Gets all activities. User can also use filters by category and type.  

 

Workflow Definition

Workflow is a template of interconnected activities. Activities are connected with each other through outputs. There is a starting activity which is the starting point of workflow. Activity has output, outputs are not only pre-defined but also can be custom made and another activity can be connected with each of those outputs. By this connections user can define the flow of the process depending on different outputs from each activity.

Workflow Definition related endpoints:

 

Lets look at each endpoint in detail.  

 

Endpoint is used for creating a workflow definition. User should specify the following properties, the ones marked with * are required.  

 

• Id is the unique identifier of the workflow definition of specific version. Workflow definition uses versioning, workflow definition with one definitionId can have several versions which is why we need the id field.
• Object owner is required and should be specified. This means that only people who are the object owners or have access to the manageable area or are a system administrator can view workflow definition.
• Name and display name properties can be used to give a name to workflow definition.
• Version is the version number of the workflow definition
• Variables are used for storing variables that might be needed throughout the workflow definition. A workflow variable is a simple key/value pair stored as part of the workflow definition and is useful for storing information that might be used by several activities.
• DeleteCompletedInstances is a Boolean that indicated whether finished workflow instance should be deleted or not
• Publish indicates whether workflow definition is published. Only published workflows can be executed.
• IsLatest indicates whether it’s the last version with the same definitionId.
• InputEntities are an array of AIHObjectType, specifying the types of input entities that can be used to execute the WorkflowDefinition.
• Metadata is used to define some FE specific configuration.
• Activities is a list of activities that are inside workflow. They have the following template:  

 

• ActivityId is the id of the activity in the database
• Type is the type of the activity which are explained in detail in the Activity section (eg. ReadLine, If/Else, SendEmail)
• Name and display name are used to describe the activity.

If you want to update something in workflow you should use the same endpoint. When you provide a definition id which already exists it is not going to create a new workflow definition but it will create a new version of the same workflow definition and set that workflow as the latest for that particular workflow definition. In this way you can modify the contents of your workflow. If you don’t specify a workflow definition or specify an Id that does not exist then a new workflow definition will be created.  

 

This endpoint can be used to delete workflow definition. For deleting workflow definition you have to specify the definition Id and all workflows that have the specified definition id will be deleted.  

 

Endpoint can be used to get all workflow definitions in the database. It has the following filters:

• Definition Id filters by the id of definition
• Name filters by the name of workflow
• Version filter has type enum and can have one of the specified values that refer to the state of workflow
• Version number refers to the integer value of the version  

 

Endpoint is used to get a particular workflow definition by its Id. Contains more detailed information about the workflow.  

Let's take a look at Parameters endpoints inside WorkflowDefinition.

 

Parameters serve as the generic method for defining inputs and outputs within a workflow.  

To designate a parameter as an input and display it in the FE during workflow execution, the Metadata field is utilized. When creating an input parameter, users need to populate the field as mentioned below:

{    "metadata": {        "type": "input"    }}

Note: All other parameters without the Metadata field defined in this way will be shown in the FE as output parameters.  

Parameter's format can be classification and it can be referenced to InputClassification entity, which needs to be predefined. InputClassifications have their separate CRUD endpoints: Note: All parameters created for the WorkflowDefinition are inherited across versions.  

 

This endpoint is used to execute workflow. User should specify the definition Id and the published version of that workflow definition. This endpoint returns workflow instance which is the instance of workflow in execution.

When executing a workflow, users have the option to pass both Parameters and InputObjects, which can then be accessed within the workflow. Parameters are custom-defined inputs for the workflow execution that can vary in format, while InputObjects are AIH entity inputs. Users can only pass InputObjects with the corresponding entity type, as predefined when creating the workflow(inside InputEntities field).

How to run workflow from FE

To run a workflow from the FE, specific configurations must be specified when creating the workflow.

• Specify InputEntities to indicate the types where you want to enable multiselect in tables, allowing you to send specific entities to the workflow.
  • InputEntities types can be defined from the following list: AIHObjectType - organization | plant | mainSystem | equipment | channel | job | schema | structure | design | file | risk | deviation | changeRequest | query | workflow | model | monitor | workItem | activity | workTemplate | activityTemplate
• Specify the placement of your workflow by filling in the Metadata field as shown below:

"metadata": {    "placement": [        "risks_risks-mainPage_topBar",        "risks_risks-mainPage_tableActionsBar",        "risks_risks-innerPage_topBar"    ]}

To structure this strings the following logic is used:

UI module name submodule name - page(main, inner) placement(topBar, tableActionsBar)

Based on this configuration, the FE displays workflows in different views

• Main page top bar:
• Main page table actions bar:
• Inner page top bar:  

Collapse to see all the supported values for placement

• explore_queries-mainPage_topBar
• explore_queries-mainPage_tableActionsBar
• explore_queries-innerPage_topBar
• explore_designExplorer-mainPage_topBar
• maintenance_workItems-mainPage_topBar
• maintenance_workItems-mainPage_tableActionsBar
• maintenance_workItems-innerPage_topBar
• maintenance_activities-mainPage_topBar
• maintenance_activities-mainPage_tableActionsBar
• maintenance_activities-innerPage_topBar
• maintenance_deviations-mainPage_topBar
• maintenance_deviations-mainPage_tableActionsBar
• maintenance_deviations-innerPage_topBar
• maintenance_workTemplates-mainPage_topBar
• maintenance_workTemplates-mainPage_tableActionsBar
• maintenance_workTemplates-innerPage_topBar
• maintenance_activityTemplates-mainPage_topBar
• maintenance_activityTemplates-mainPage_tableActionsBar
• maintenance_activityTemplates-innerPage_topBar
• risks_risks-mainPage_topBar
• risks_risks-mainPage_tableActionsBar
• risks_risks-innerPage_topBar
• risks_changeRequests-mainPage_topBar
• risks_changeRequests-mainPage_tableActionsBar
• risks_changeRequests-innerPage_topBar
• monitors_monitors-mainPage_topBar
• monitors_monitors-mainPage_tableActionsBar
• monitors_monitors-innerPage_topBar
• monitors_models-mainPage_topBar
• monitors_models-mainPage_tableActionsBar
• monitors_models-innerPage_topBar
• signals_channels-mainPage_topBar
• signals_channels-mainPage_tableActionsBar
• signals_channels-innerPage_topBar
• assets_explorer-mainPage_topBar
• assets_plants-mainPage_topBar
• assets_plants-mainPage_tableActionsBar
• assets_plants-innerPage_topBar
• assets_mainSystems-mainPage_topBar
• assets_mainSystems-mainPage_tableActionsBar
• assets_mainSystems-innerPage_topBar
• assets_equipment-mainPage_topBar
• assets_equipment-mainPage_tableActionsBar
• assets_equipment-innerPage_topBar
• assets_organizations-mainPage_topBar
• assets_organizations-mainPage_tableActionsBar
• assets_organizations-innerPage_topBar
• assets_explorer-mainPage_topBar
• assets_settings-mainPage_topBar
• assets_settings-mainPage_tableActionsBar
• designs_designs-mainPage_topBar
• designs_designs-mainPage_tableActionsBar
• designs_designs-innerPage_topBar
• designs_structures-mainPage_topBar
• designs_structures-mainPage_tableActionsBar
• designs_structures-innerPage_topBar
• designs_schemas-mainPage_topBar
• designs_schemas-mainPage_tableActionsBar
• designs_schemas-innerPage_topBar
• designs_settings-mainPage_topBar
• admin_users-mainPage_topBar
• admin_users-mainPage_tableActionsBar
• admin_teams-mainPage_topBar
• admin_teams-mainPage_tableActionsBar

Workflow Instance

Workflow Instance is one particular execution of the workflow definition. When we execute a workflow definition a new instance is created.

Workflow Instance related endpoints:

 

Lets look at each endpoint in detail.  

 

Endpoint is used to delete a particular workflow instance.  

 

Endpoint is used for getting all workflow instances. It has the following filters:

• Workflow Definition Id filters by workflow definition id
• Workflow Status is an enum, filters by status of the instance, can be one of the specified values
• OrderBy sorts the result in an order, latest by the date are on the top
• SearchTerm filters by the specified term  

 

Endpoint is used to get a particular workflow instance. Contains detailed information about the instance.  

 

CreatedBy specifies the individual who executed the workflow.  

WorkflowStatus indicates the state of workflow.

• Idle - when workflow is still not finished but currently is in the waiting state
• Running - when workflow is currently running
• Finished - when workflow has finished its execution
• Suspended - when workflow is temporarily stopped
• Faulted - when during execution an error occurs and workflow is unable to proceed to the next step
• Cancelled - when workflow instance is manually cancelled  

 

Endpoint is used to get the execution logs of workflow instance. Contains detailed information about every activity of workflow. Starting time, ending time and activity output are also included in execution logs.  

 

Endpoint is used to retrieve all parameters that the workflow has, using values passed during execution; if no values are passed, default values are utilized.  

 

Endpoint is used to cancel workflow execution.  

Change requests

Change requests are used in AIH to create a request for creating/updating/deleting an object in AIH. Before the introduction of change requests only users who had the permission could create/update/delete an object in AIH. Now, users can create a change request and after passing the review stage the changes will be applied to the real environment. Currently change requests in AIH are supported only in Risks.

Change request related endpoints:

 

Lets look at each endpoint in detail.  

 

Endpoint is used to create a change request. It has the following schema:  

 

• Id is the identifier of the change request. If null value is provided it will be autogenerated
• ReferenceId is another identifier for change request, is used to display the change request in the FE of the application
• Object owner is the owner of the change request. The field is required and should be specified
• Type is the area that the change request relates to, currently only risks area is supported from the FE of the application
• Title is required, is the title of the change request
• Description can be used to describe the change request
• Status indicates the current state of the change request
  • Created – when a change request is created but is not submitted for review yet its in the created stage
  • Pending – when a change request is submitted for review, its state becomes pending
  • Abandoned – used for deleting a change request, only abandoned change requests can be deleted
  • Approved – when all required reviewers approve the change request the change request status becomes approved
  • Declined – when not all required reviewers have approved the change request meaning that at least one required reviewer or all of them declined the change request its state is set to declined
  • Applied – after all required reviewers have approved the change request, the workflow tries to make all specified changes in the real environment. If everything is successful change requests status is set to applied
  • Failed – If the workflow cannot apply the changes in the real environment and some error occurs which stops the process, the change requests status becomes failed
• CorrelationId indicates the main entity in the change request. Change request can contain several objects, e.g. the user can try to create a risk, a mitigation and a population with one change request. Since in that case mitigation and population will relate to a particular risk the correlation id indicates the risk id, or the id of the main object of the change request
• Items is the array of objects that the user wants to create/update/delete with the change request. It has the following structure:  

 

• Id is the identifier of the change request item. If null value is provided it will be autogenerated
• Type is the type of the object e.g. we are creating a risk then the type will be risk
• Action specifies the action that we want to do on an object
• LinkedEntityType can be used to indicate a connection between two objects
• DestinationURL contains the endpoint of the real environment where after passing through the review stage the object will be applied
• New data and Old data contain the information about the state of the object before and after the change request in a json format
• Priority is the priority by which the objects will be applied to the real environment. If we are creating a risk and mitigation that is related to that risk in one change request then the risk object should be created first meaning that the priority of the risk object should be higher than that of a mitigation.

When a change request is submitted for review, a workflow runs which sets predefined reviewers to the change request and notifies those people that a new change request was submitted. After the workflow finishes its execution a change request has reviewers assigned to it.  

 

Endpoint is used to update the change request. Applied change request cannot be updated.  

 

Gets the change request by Id. Response also includes reviewers and comments of the change request.  

 

Users can add comments to the change request. For adding comments change request id should be specified.  

 

• CommentText is the text of the comment
• Commenter contains information about the user who creates the comment.  

 

Endpoint is used to update the state of the change request review. When a reviewer approves the change request this endpoint is being called to update the state of the review. When all required reviewers have approved the change request another workflow is being triggered which tries to apply the changes in the real environment.  

 

Endpoint is used for getting all change requests.  

 

It has the following filters:

• ObjectOwnerId filters by the id of the object owner
• ChangeRequestType filters by the area of the change request
• EntityId filters by a specific object id of the change request
• EntityType filters by the type of the entity
• LinkedEntityType filters by the linked entity type
• EntityAction filters by the action type of the change request items
• Status filters by the status of the change request
• Correlation Id filters by the correlation Id property of the change request
• ReviewerId filers by the reviewer Id, used for getting all change requests of a particular reviewer  

 

Endpoint is used for deleting the change request. Only abandoned change requests can be deleted.