Starting a Case from Outside of Questetra BPM Suite (Pre-upload Chapter)

Starting a Case After Pre-uploading Files

In the curl and Python Chapters, we sent the file body along with other parameters in multipart/form-data format to pass values to File-type Data Items. However, [Message Start Event (HTTP)] provides another method: “Pre-uploading”, where you upload the files first, receive file IDs, and then send those IDs in the request to start a case. In this post, we will explain this process using curl and Python.

Pre-uploading is available for [Message Start Event (HTTP)]. It cannot be used with [Receive Task (HTTP)].

Pre-uploading becomes necessary when the total size of the attached files is large. A multipart/form-data request received by [Message Start Event (HTTP)] has a maximum total limit of 100 MB, including all files and parameters. While sending the file body together with other parameters cannot exceed this limit, pre-uploading allows you to upload files separately, enabling you to attach files that total more than 100 MB.

We will use the same Workflow App as in the curl Chapter. If you haven’t created it yet, please refer to “Sending a variety of data > App Settings” in the Preparatory Chapter and curl Chapter to set up and release the app.

Procedure Overview

Pre-uploading involves sending two HTTP requests.

Upload the File: Send the API key and file to /File/upload in multipart/form-data format. An ID for each file will be returned in the response.
Start the Case: Send the IDs received in Step 1 as values for the File-type parameters to /start, along with the other parameters.

Request	URL	Content-Type
File Upload	`https://example.questetra.net/System/Event/MessageStart/{processModelInfoId}/{nodeNumber}/File/upload`	multipart/form-data
Case Start	`https://example.questetra.net/System/Event/MessageStart/{processModelInfoId}/{nodeNumber}/start`	application/x-www-form-urlencoded

The {processModelInfoId} and {nodeNumber} values are the same as those used in the Case Start URL.

Starting a Case with curl

1. Upload the File

curl https://example.questetra.net/System/Event/MessageStart/{processModelInfoId}/{nodeNumber}/File/upload ^
  -F "key={API Key}" ^
  -F "files=@ques-kun-01.png" ^
  -F "files=@ques-kun-02.png"

The parameter name for passing files is fixed as files, rather than using the field name of the Data Item. When uploading multiple files, repeat files for each one. Pass the API key using the same key parameter as when starting a case.

Upon a successful upload, JSON structured like the following will be returned:

{
  "files": [
    {
      "id": "12345:AbCdEfGhIjKlMnOp",
      "name": "ques-kun-01.png",
      "contentType": "image/png",
>      "length": 34567,
      "lengthText": "33.8 KB",
      "image": true,
      "inline": false,
      "malwareScanStatus": "NO_THREATS_FOUND"
>    },
    {
      "id": "12346:QrStUvWxYzAbCdEf",
      "name": "ques-kun-02.png",
      "contentType": "image/png",
      "length": 45678,
      "lengthText": "44.7 KB",
      "image": true,
      "inline": false,
      "malwareScanStatus": "NO_THREATS_FOUND"
    }
  ]
}

What you will use to start the case is the value of files[].id. Since it is a string formatted as the file number joined with an access token by a colon, pass it directly as-is to the next request.

2. Start the Case

curl https://example.questetra.net/System/Event/MessageStart/{processModelInfoId}/{nodeNumber}/start ^
  --data-urlencode "key={API Key}" ^
  --data-urlencode "title=Test" ^
  --data-urlencode "q_str=This is a case start test" ^
  --data-urlencode "q_file=12345:AbCdEfGhIjKlMnOp" ^
  --data-urlencode "q_file=12346:QrStUvWxYzAbCdEf"

Pass the ID received during the upload step to the File-type parameter q_file. When attaching multiple files, repeat the parameter name just as you did when sending the actual file body in the curl Chapter. Because you are not sending the actual file payload here, you can transmit the request using the --data-urlencode option instead of the -F option required when sending File-type Data Items in the curl Chapter.

Please send the request to start a case in application/x-www-form-urlencoded format. If sent in multipart/form-data format, the IDs will not be accepted, and the case will start without the files attached.

Starting a Case with Python

As in the Python Chapter, we will use the requests package. Extract the IDs from the upload response and add them to the case start parameters.

import requests

# API Endpoint
base_url = 'https://example.questetra.net/System/Event/MessageStart/{processModelInfoId}/{nodeNumber}'
api_key = '{API Key}'

# 1. Upload the files
files = [ # Parameter name is fixed as 'files'
    ('files', ('ques-kun-01.png', open('./ques-kun-01.png', 'rb'), 'image/png')),
    ('files', ('ques-kun-02.png', open('./ques-kun-02.png', 'rb'), 'image/png')),
]
r = requests.post(f'{base_url}/File/upload', data={'key': api_key}, files=files)
r.raise_for_status()
file_ids = [f['id'] for f in r.json()['files']] # List of IDs

# 2. Start the case
params = [ # Use a list of tuples instead of a dict to repeat parameter names
    ('key', api_key),
    ('title', 'Test'),
    ('q_str', 'This is a case start test'),
]
params += [('q_file', file_id) for file_id in file_ids]
r = requests.post(f'{base_url}/start', data=params) # Sent as application/x-www-form-urlencoded since 'files' is omitted
r.raise_for_status()
print(f'Status Code: {r.status_code}')
print(r.text)

As explained in the Python Chapter, requests sends data formatted as application/x-www-form-urlencoded as long as you do not pass files. Omit files in the request to start a case, and include the IDs within data instead.

Important Notes on Pre-uploading

The maximum limit for a single upload is 100 MB. This is the same limit as the request to start a case. If the total size exceeds this, upload the files across multiple requests.
The ID is valid for 1 hour. Please use the ID to start a case within 1 hour of uploading.
The ID can only be used once. An ID used to start a case becomes invalid afterward. If you want to attach the same file to a different case, please upload it again. If starting a case fails due to an input error, the ID has not been consumed yet, so you can retry starting the case using the same ID.

Summary

By using pre-uploading, you can send files in advance and build your case start request using only string parameters. Make use of this method when you need to attach files that exceed the single-request limit. In the next post, “Troubleshooting Errors Chapter,” we will introduce how to view and handle errors when a case fails to start.