Example of how to create workflows using the new SoftExpert Workflow API

info

This tutorial aims to provide a brief demonstration on how to create a workflow in the SoftExpert Workflow component using a REST API. It is not a thorough guide on integrations, but rather a practical illustration for request creation.

Introduction

In this tutorial, we will demonstrate how to use the new API of the SoftExpert Workflow component for instance creation. This API was totally designed using the REST standard, which means that we can use it to send HTTP requests and get responses in the JSON format.

By using this new API, we can easily automate the instance creation process, which can be very useful in scenarios in which we need to create multiple instances for the same process quickly and efficiently.

Moreover, by using a REST API, we have the advantage of being able to easily integrate other tools and systems, since this standard is largely adopted in the software industry.

Resource URL

POST /apigateway/v1/workflow

Example

In this workflow instance creation example, we will add an attachment using the SoftExpert Suite generic upload API.

The SoftExpert Suite upload API allows importing electronic files of several types (such as images, spreadsheets, text files, and more) in order for them to be loaded in SoftExpert Suite and, usually, associated with a specific component.

To illustrate this tutorial and fully use the REST API features of the SoftExpert Workflow component, we will demonstrate how to upload an electronic file, and then associate its hash with the next request.

Importing an electronic file to the upload API

To import an attachment using the file upload API, we first need to send a request to the /apigateway/v1/file/upload URL. This request must include the file we want to send, along with some optional metadata, such as file name and a description.

GET /apigateway/v1/file/upload

Supported attributes:

Request Body Parameter	Type	Required	Description
file	multipart/form-data	Yes	One single file, provided in the multipart/form-data encoding.

Request example:

curl -X POST 'https://my-domain.softexpert.com/apigateway/v1/file/upload' \
-H 'Authorization: <your_api_token>' \
-F 'file=@"/mnt/c/Users/jsilva/Downloads/DT22.PT0007 - 00 - DOCUMENTATION-2.2-PT_BR-Guia de integração.pdf"'

After sending the request, the API will return a JSON object containing important information. This information includes a description informing that the file has been sent successfully, a unique hash identifying the file, and the status of the operation.

Response example:

{
  "description": "File uploaded successfully.",
  "filehash": "2c9280868793d127018793e590790098",
  "status": "success"
}

Upon receiving this response, we can use the returned hash to reference the file in other parts of our application, such as in the SoftExpert Workflow instance. It is important to remember that the hash is unique for each sent file, which ensures that we will always have a reliable reference to the file.

Creating a new workflow

After creating the hash of the electronic file, we need to send a request to the SoftExpert Workflow API with the following parameters:

Supported attributes:

Request Body Parameter	Type	Required	Description
workflowTypeId	String	No	Workflow type ID # (replace)
processId	String	Yes	Process ID #
workflowTitle	String	Yes	Workflow instance title
userId	String	No	User ID
tables	String	No	Table list
tables.id	String	No	Table ID #
tables.fields.id	String	No	Table field ID #; if the tables.fields.type object is set with LIST value, the relationship ID # will have to be sent.
tables.fields.value		No	Table field value
tables.fields.type	String	No	Field type of the "LIST"" table (optional)
attachments	String	No	Attachment list
attachments.filereference	String	No	Hash of the attachment to be imported
attachments.name	String	No	Attachment name

Possible data types of the table fields:

Icon	Data type	Description
	Text (255)	Simple text
	Text (unlimited)	Long text
	Numeric	Integer
	Decimal	Decimal number
	Date	Date (YYYY-MM-DD)
	Time	Time (HH:mm).
	Boolean	Single selection
	Simple list	List with options
	Group of options	Grouped options

Request example:

{
  "processId": "Your process identifier",
  "workflowTitle": "Your Title Instance",
  "userId": "Your Tituser Idle Instance",
  "tables": [
    {
      "id": "Your Table Identifier",
      "fields": [
        {
          "id": "text1",
          "value": "abc"
        }
      ]
    }
  ],
  "attachments": [
    {
      "filereference": "2c94808680f0ee390180f5c5b4c02054",
      "name": "testejson"
    }
  ]
}

Response example:

Related articles

• Installing and using curl