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

• Access to the Workflow Designer for designing the workflow.
• 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 for configuring the workflow.
• Optionally, access to the Collibra Console for troubleshooting.

Accessing the Collibra API documentation

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

   

3. On the API documentation page, select the Java 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 Platform. There are several ways of retrieving the UUID of a resource as mentioned in the Finding resource IDs section of the Collibra Documentation. The easiest way to retrieve the UUID is from the URL of a resource:

https://<your_collibra_url>/<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.

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()

// #importFile NONE
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 out-of-the-box New Business Terms domain and Acronym asset type.

Set asset attributes

To set asset attributes, 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()

// #importFile NONE
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 ID with a valid one.

Other attribute actions

Setting attribute values means that existing values are replaced with the ones specified. To add attributes of the same type or modify existing attributes, use the AttributeApi interface.

You can add one attribute using the addAttribute() method. The following example adds an attribute of the type specified by the attributeType variable, with the value of the attributeValue variable to the asset where the workflow was started. Both variables hold String values.

// #importFile NONE
import com.collibra.dgc.core.api.dto.instance.attribute.AddAttributeRequest

attributeApi.addAttribute(AddAttributeRequest.builder()
	.assetId(item.getId())
	.typeId(string2Uuid(attributeType))
	.value(attributeValue)
	.build()
)

You can add multiple attributes at once by using the addAttributes() method with a list of addAttributeRequest objects, for example:

// #importFile NONE
import com.collibra.dgc.core.api.dto.instance.attribute.AddAttributeRequest

List<AddAttributeRequest> attributesList = []

attributesList.add(AddAttributeRequest.builder()
	.assetId(item.getId())
	.typeId(string2Uuid(attributeType1))
	.value(attributeValue1)
	.build()
)

attributesList.add(AddAttributeRequest.builder()
	.assetId(item.getId())
	.typeId(string2Uuid(attributeType2))
	.value(attributeValue2)
	.build()
)

attributeApi.addAttributes(attributesList)

To modify existing attributes, you must first determine their ID and then use the changeAttribute() method to update them. The following example updates the most recently added attribute of the type specified by the attributeType variable with the value of the attributeValue variable for the asset where the workflow was started.

// #importFile NONE
import com.collibra.dgc.core.api.dto.instance.attribute.FindAttributesRequest
import com.collibra.dgc.core.api.dto.instance.attribute.ChangeAttributeRequest

UUID attributeId = attributeApi.findAttributes(FindAttributesRequest.builder()
	.assetId(item.getId())
	.typeIds([attributeType])
	.build()
).getResults().get(0).getId()

attributeApi.changeAttribute(ChangeAttributeRequest.builder()
	.id(attributeId)
	.value(attributeValue)
	.build()
)

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()

// #importFile NONE
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 out-of-the-box New Business Terms domain, adds a description and changes the status to Approved.

// #importFile NONE
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()
)

Additional resources

• Read the Getting started with workflows Workflow Designer documentation section.
• Read the Using workflows Collibra Documentation section.
• Consult the Java API documentation: https://<your_collibra_url>/javadocs/javav2/index.html.