Introduction to builders

In this tutorial you learn how to configure automated tasks inside workflows by using scripts and builders. Builders perform multiple steps to create and configure objects via the build() method and return the fully constructed object. You will create a new asset, add attributes to the asset and modify the asset status.

Prerequisites

• Eclipse IDE.
• Flowable Eclipse Designer plugin.
• Access to a Collibra environment as a user with the Sysadmin global role or a global role that has at least the Workflow Administration global permission.
• Access to the Collibra Console for troubleshooting.

For more installation details and to get familiar with the Eclipse IDE interface, see Getting Started with workflows.

Create a script task

Open Eclipse IDE and

1. Create a new Flowable project and diagram.
2. Add a pool and configure its properties.
3. Add a start event, a script task, an end event and connect them.

For more information on how to create a Flowable project and diagram, see the Getting started with workflows and the Hello World! tutorials.

Add support for Groovy

If you prefer using your own editor to write the Groovy script, you can skip this step.

The Apache Groovy programming language allows for easy interoperability between the Java and Collibra libraries.

To add support for Groovy syntax highlight and auto-completion in Eclipse:

1. In the menu bar, click Help → Install New Software....

   

2. In the Available Software window, click Add.

   

3. In the Add Repository window:
   1. Enter a Name, for example Groovy-Eclipse.
   2. Enter the appropriate link for your Eclipse version as specified on the Groovy-Eclipse page in the Location field. We are using https://dist.springsource.org/release/GRECLIPSE/e4.9 in this example.

      

   3. Click Add to close the Add Repository window.
4. In the Available Software window, select the Main Package check box.
5. Ensure the Contact all update sites during install to find required software check box is selected and click Next.

   

6. Review the installation details and click Next.
7. Review, accept the license agreements, and click Finish.
8. If you are prompted with a security warning, click Install anyway.

   

9. Click Restart Now to finish the installation.

For more installation instructions, see the Groovy-Eclipse documentation.

Add support for Collibra Java API v2

If you prefer using your own editor to write the Groovy script, you can skip this step or adapt it to your editor.

1. Download the Collibra Java API library version 2:
   1. Go to the Collibra Community Downloads page.
   2. Select your Collibra Data Intelligence Platform version.
   3. Download the dgc-core-<version>-apiv2.jar file.
2. In Eclipse, create a new folder inside your project:
   1. In the Flowable Explorer tab, right-click your project name.
   2. Select New → Folder.
   3. In the New Folder window, enter a name for the folder and click Finish. We are using lib in this example.

      

3. Move the downloaded JAR file to the new folder.

   Refresh the folder if you can't see the file you just added.

4. In the Flowable Explorer tab, right-click your project name and select Properties → Java Build Path → Libraries.
5. In the Libraries tab of the Java Build Path section, click Add JARs....

   

6. In the JAR Selection window, select the Java API library version 2 JAR file and click OK.

   

7. In the Properties window, click Apply and Close.

   

Create a Groovy script file

If you prefer using your own editor to write the Groovy script, you can skip this step and create a new Groovy script file inside your editor.

1. In the Flowable Explorer tab, right-click your project name and select New → Other.
2. In the New window, expand the Groovy folder, select Groovy Type and click Next.

   

3. In the New Groovy Type window, change the Kind to Script.
4. Enter a name for your new file and click Finish. We are using newAsset in this example.

   

The newAsset.groovy file is added to your project and displayed in the Shared Area.

Accessing the Collibra API documentation

1. In your Collibra Data Intelligence Platform environment, click in the upper-right corner.
2. Click API documentation.

   

3. On the API documentation page, click Core API.

   

Working with the Collibra Java API builders

All the supported asset related operations are listed under the AssetApi interface in the Collibra Java API documentation.

In the context of workflow script tasks, the <Resource>Api interfaces (such as AssetApi, CommunityTypeApi, FileApi, and so on) are already instantiated and accessible via <resource>Api variables (such as assetApi, communityTypeApi, fileApi, and so on).

The API makes use of universally unique identifiers (UUIDs) to find resources in Collibra Data Intelligence Platform. There are several ways of retrieving the UUID of a resource as mentioned in the Finding resource IDs section of the Administration Guide. The easiest way to retrieve the UUID is from the URL of a resource:

https://<yourdgcinstance>/<resource type>/00000000-0000-0000-0001-000100000001

In Collibra Java API v2, the UUID is provided as a string via the string2Uuid() helper method.

Before referring to any class, you must first have a reference to their packages. You resolve class references via the import statement. There are several ways to add imports to the script file. The easiest way is to use the auto-complete feature by pressing Ctrl / command + space when typing the class and selecting one of the available options:

Eclipse automatically completes the name of the class and adds the necessary import declaration at the beginning of the file.

Because each script task is independent, include import statements for all the packages you are using in a script for each script task. Avoid using generic imports to reduce execution time.

Create a new asset

To create a new asset, use the addAsset() method which requires an AddAssetRequest parameter. The AddAssetRequest class has a builder() method available.

• Class: AssetApi
  • Main method: AddAsset()
    • Parameter and builder method: AddAssetRequest.builder()

import com.collibra.dgc.core.api.dto.instance.asset.AddAssetRequest

	assetApi.addAsset(AddAssetRequest.builder()
	.name("DGC")
	.typeId(string2Uuid("00000000-0000-0000-0000-000000011003"))
	.domainId(string2Uuid("00000000-0000-0000-0000-000000006013"))
	.build()
);

The command works for the packaged New Business Terms domain and Acronym asset type.

Add attributes to an asset

To add attributes to an asset, use the setAssetAttributes() method which requires a SetAssetAttributesRequest parameter. The SetAssetAttributesRequest class has a builder() method available.

• Class: AssetApi
  • Main method: setAssetAttributes()
    • Parameter and builder method: SetAssetAttributesRequest.builder()

import com.collibra.dgc.core.api.dto.instance.asset.SetAssetAttributesRequest

assetApi.setAssetAttributes(SetAssetAttributesRequest.builder()
	.assetId(
		string2Uuid("1b2f8eb4-4f13-4cd2-a238-9a7d9666a93a")
	)
	.typeId(
		string2Uuid("00000000-0000-0000-0000-000000000202")
	)
	.values(["Data Governance Center"])
	.build()
);

The command sets the definition of the asset to Data Governance Center. The command does not work unless you replace the asset UUID with a valid one.

Modify an asset

To modify an asset, use the changeAsset() method which requires a changeAssetRequest parameter. The changeAssetRequest class has a builder() method available.

• Class: AssetApi
  • Main method: changeAsset()
    • Parameter and builder method: ChangeAssetRequest.builder()

import com.collibra.dgc.core.api.dto.instance.asset.ChangeAssetRequest

assetApi.changeAsset(ChangeAssetRequest.builder()
	.id(
		string2Uuid("1b2f8eb4-4f13-4cd2-a238-9a7d9666a93a")
	)
	.statusId(
		string2Uuid("00000000-0000-0000-0000-000000005009")
	)
	.build()
);

The command changes the status of the asset to Approved. The command does not work unless you replace the asset UUID with a valid one.

Multiple operations

This example creates a new acronym GDPR in the packaged New Business Terms domain, adds a description and changes the status to Approved.

import com.collibra.dgc.core.api.dto.instance.asset.AddAssetRequest
import com.collibra.dgc.core.api.dto.instance.asset.ChangeAssetRequest
import com.collibra.dgc.core.api.dto.instance.asset.SetAssetAttributesRequest
import com.collibra.dgc.core.api.model.instance.Asset

Asset GDPR = assetApi.addAsset(AddAssetRequest.builder()
	.name("GDPR")
	.typeId(
		string2Uuid("00000000-0000-0000-0000-000000011003")
	)
	.domainId(
		string2Uuid("00000000-0000-0000-0000-000000006013")
	)
	.build()
);

assetApi.setAssetAttributes(SetAssetAttributesRequest.builder()
	.assetId(GDPR.getId())
	.values(["General Data Protection Regulation"])
	.typeId(
		string2Uuid("00000000-0000-0000-0000-000000000202")
	)
	.build()
);

assetApi.changeAsset(ChangeAssetRequest.builder()
	.id(GDPR.getId())
	.statusId(
		string2Uuid("00000000-0000-0000-0000-000000005009")
	)
	.build()
);

Use the script inside a workflow

You can use any of the examples in this tutorial or create your own script and add it to the workflow you have created:

1. Copy the code.
2. On the workflow diagram, select the script task.
3. In the properties view, select the Main Config section.
4. From the Script language drop-down menu, select groovy.
5. Paste the code in the Script filed.

   

6. Save the diagram and upload the BPMN file to Collibra Data Intelligence Platform.
7. Configure and enable the workflow in the Settings section of Collibra.
8. Start the workflow.

If there are no errors, the assets are created or modified in Collibra. You will find them in the Business Glossary application, under the All Business Assets view.

Troubleshooting

In case of errors, the workflow does not start, and an error message is displayed.

The logs contain more information about the error:

1. Open Collibra Console.
   Collibra Console opens with the Infrastructure page.
2. Click the name of the environment you deployed the workflow in to display its details.
3. Select Data Governance Center.
4. Select Logs → dgc.log

Look for errors related to Java or Groovy.

Next steps

You have created a workflow that adds a new acronym and sets its properties and saw the results in Collibra Data Intelligence Platform.

The next tutorial will test your knowledge about user and script tasks, delegates and exclusive gateways as you build a complex workflow.

Additional resources

• Read the Getting started with workflows Collibra Administration Guide section.
• Read the Using workflows Collibra User Guide section.
• Consult the java documentation: https://<your_dgc_environment_url>/docs/javav2/index.html.