BPM, Workflow, and Case

Technique for Importing Business Objects into Workflow

To describe the structure of data in Workflow you define business objects, which are normally created in the designer.  However, what if you have some external types already defined and want to import them to save time, effort, and transcribing errors?  This blog will outline one such technique. This technique and the tools are provided as-is, but please contact me with any questions or issues you have.

Note that there are existing feature requests for first-class support of importing data types.  Please give them an upvote if you require this support:
https://ideas.ibm.com/ideas/IWF-I-1033

https://ideas.ibm.com/ideas/DBALC-I-7

Without a first-class feature, we can leverage the external service capabilities with a custom utility to import the types and make them editable just like any other business objects that are authored.  An external service may be used to call a REST API.  In order to call the service, the data types used in the parameters of the operation are imported as read-only business objects.  We'll use an example to illustrate the process.  Below are the contents of a file called dataTypeImport.json.  Note some important features of this OpenAPI:

• The title, server URL, description, path names are all filled with values that will not be used for any meaningful purpose
• All types to be imported must be referenced, directly or indirectly, from operations in the OpenAPI
• We use one operation that points to a wrapper type, which in turn references all types that we want to import. This was done to ensure that the BO names are maintained during import.

{
	"openapi": "3.0.2",
	"info": {
		"title": "Data type import wrapper",
		"description": "",
		"version": "1.0"
	},
	"servers": [{
		"url": "http://not.a.real.server:8080/api"
	}],
	"paths": {
		"/fakePath": {
			"get": {
				"summary": "Finds Pets by status",
				"description": "Fake operation to reference types",
				"operationId": "fakeOpId",
				"parameters": [{
					"name": "wrapperType",
					"in": "query",
					"schema": {
						"$ref": "#/components/schemas/WrapperType"
					}
				}],
				"responses": {
					"200": {
						"description": "successful operation",
						"content": {
							"application/json": {
								"schema": {
									"type": "string"
								}
							}
						}
					}
				}
			}
		}
	},
	"components": {
		"schemas": {
			"WrapperType": {
				"type": "object",
				"properties": {
					"order": {
						"$ref": "#/components/schemas/Order"
					},
					"customer": {
						"$ref": "#/components/schemas/Customer"
					},
					"user": {
						"$ref": "#/components/schemas/User"
					},
					"address": {
						"$ref": "#/components/schemas/Address"
					}
				}
			},
			"Order": {
				"type": "object",
				"properties": {
					"id": {
						"type": "integer",
						"format": "int32"
					},
					"widgetId": {
						"type": "integer",
						"format": "int32"
					},
					"quantity": {
						"type": "integer",
						"format": "int32"
					},
					"orderDate": {
						"type": "string",
						"format": "date-time"
					},
					"status": {
						"type": "string",
						"description": "Order Status",
						"example": "approved",
						"enum": ["placed", "approved", "delivered"]
					},
					"complete": {
						"type": "boolean"
					}
				}
			},
			"Customer": {
				"type": "object",
				"properties": {
					"id": {
						"type": "integer",
						"format": "int32"
					},
					"username": {
						"type": "string"
					},
					"address": {
						"type": "array",
						"items": {
							"$ref": "#/components/schemas/Address"
						}
					}
				}
			},
			"Address": {
				"type": "object",
				"properties": {
					"street": {
						"type": "string"
					},
					"city": {
						"type": "string"
					},
					"state": {
						"type": "string"
					},
					"zip": {
						"type": "string"
					}
				}
			},
			"User": {
				"type": "object",
				"properties": {
					"id": {
						"type": "integer",
						"format": "int32"
					},
					"username": {
						"type": "string"
					},
					"firstName": {
						"type": "string"
					},
					"lastName": {
						"type": "string"
					},
					"email": {
						"type": "string"
					},
					"password": {
						"type": "string"
					},
					"phone": {
						"type": "string"
					},
					"userStatus": {
						"type": "integer",
						"format": "int32"
					}
				}
			}
		}
	}
}

After completing the wizard we get an external service artifact in the library, a server entry in the project settings editor, and what we're really after: imported business objects:

The problem now is that the business objects are not editable, are tagged as discovered, and if we delete the external service then the business objects will also be deleted.  Using a custom utility, we can process the project to get to a state where the business objects behave as if we authored them ourselves.  The utility is located here.

The next step is to create a version of the toolkit or project and export the twx file.  Unzip the twx to a temporary folder on your system.  We'll run the utility against these unzipped contents.

Run the Java utility to process the folder with any JVM level 1.6 or higher.  The arguments are:

1. The folder location of the unzipped content
2. The new version number to use.  If you just exported "V1", then you'd most likely input V2 to the tool.

Here's an example invocation. I downloaded the jar to "C:\grant\samplePlugins\ConvertReadOnlyBOs\" and unzipped my twx file to "C:\unzip\".  I want the new version to be V2.

java -cp C:\grant\samplePlugins\ConvertReadOnlyBOs\convertReadOnlyBOs.jar com.grant.boconvert.ConvertReadOnlyBOs C:\unzip\ V2

If the tool runs successfully, you should see a message like this:

Zip up the contents of the folder and import the zip file back into BA Studio or Workflow Center. You should now see that the BOs are editable and the external service is cleaned up.  In my sample, I would also delete the wrapper type used to reference all the other types.  You can also manually delete the server entry and the external service artifact.

Congratulations, you have imported the business objects and can now treat them like any other authored types!!