Skip to main content

API Reference for Workflow Activities

The CMDBuild Workflow API provides programmatic access to core platform features from within automated workflow activities. It supports operations such as process variable manipulation, card and relation lifecycle management, email dispatch, and report generation.

Key words​

The following keywords are reserved variables automatically available within the workflow script. They provide access to contextual information about the current process execution and the CMDBuild API.

Process​

  • ProcessId — Long
    Id of the current process

  • ProcessClass — String
    Class name of the current process

  • ProcessCode — String
    Univocal ProcessInstanceId of the current process

Performer​

  • _CurrentUser — ReferenceType
    Reference to the User that performed the last activity of the current process

  • _CurrentGroup — ReferenceType
    Reference to the Role that performed the last activity of the current process

API​

  • cmdb
    Identifies the native functions in CMDBuild

Management of CMDBuild items​

The following classes represent the CMDBuild-specific data types used within workflow scripts. Each type exposes a set of methods to read and manipulate its properties. For other primitive data types (integer, string, date, float) you can use the standard manipulation methods offered by the Java language.

ReferenceType​

  • getId() — Long
    Returns the Reference id

  • getDescription() — String
    Returns the Reference description

LookupType​

  • getId() — Long
    Returns the Lookup id

  • getType() — String
    Returns the type of Lookup

  • getDescription() — String
    Returns the Lookup description

  • getCode() — String
    Returns the Lookup code

CardDescriptor​

  • getClassName() — String
    Returns the Class name for a CardDescriptor variable

  • getId() — Long
    Returns the Id for a CardDescriptor variable

  • equals(CardDescriptor cardDescriptor) — boolean
    Compares the CardDescriptor variable with the specified one

Card​

  • getCode() — String
    Returns the Code for a Card variable

  • getDescription() — String
    Returns the Description for a Card variable

  • has(String name) — boolean
    Controls the presence of the specified attribute in the Card variable

  • hasAttribute(String name) — boolean
    Controls the presence of the specified attribute in the Card variable

  • get(String name) — Object
    Returns the specified attribute value of the Card variable

  • getAttributeNames() — Set<String>
    Returns the attributes list of the Card variable

  • getAttributes() — Map<String, Object>
    Returns the attributes list and their values of the Card variable. The returned values respect the CMDBuild types (ReferenceType, LookupType, Date, Integer, ...)

Attachments​

  • fetch() — Iterable<AttachmentDescriptor>
    Returns the attachments list of the Card or of the instantiated process

  • upload(Attachment... attachments) — void
    Attaches the documents to the card or to the instantiated process

  • upload(String name, String description, String category, String url) — void
    Creates an attachment with the specified name, description and category starting from the file with the specified URL and attaches it to the card or to the instantiated process

  • selectByName(String... names) — SelectedAttachments
    Returns the attachments of the card or of the instantiated process with the specified name

  • selectAll() — SelectedAttachments
    Returns all attachments of the card or of the instantiated process

AttachmentDescriptor​

  • getName() — String
    Returns the name of the attachment

  • getDescription() — String
    Returns the attachment description

  • getCategory() — String
    Returns the attachment category

Attachment​

  • getUrl() — String
    Returns the URL of the file

DownloadedReport​

  • getUrl() — String
    Returns the local URL where the report has been saved

  • equals(DownloadedReport downloadedReport) — boolean
    Compares the DownloadedReport variable with the specified one

Access methods to CMDBuild​

The following APIs allow workflow scripts to interact with CMDBuild data. Each API follows a fluent builder pattern: start with a Builder to initialize the operation, optionally chain one or more Modifiers to configure it, then call an Action to execute it.

NewCard​

Builders​

  • newCard(String className) — NewCard
    Creates a new Card in the specified Class of CMDBuild

Modifiers​

  • withCode(String value) — NewCard
    Adds the Code to the new Card created in CMDBuild

  • withDescription(String value) — NewCard
    Adds the Description to the new Card created in CMDBuild

  • with(String name, Object value) — NewCard
    Adds the specified value for the specified attribute to the new Card created in CMDBuild

  • withAttribute(String name, Object value) — NewCard
    Adds the specified value for the specified attribute to the new Card created in CMDBuild

Actions​

  • create() — CardDescriptor
    Creates the new Card in CMDBuild setting the previously defined attributes

Example

/*
  * Creation of a new card in the "Employee" class having
  * the following attributes:
  * "Code" = "T1000"
  * "Name" = "James"
  * "Surname" = "Hetfield"
*/

cdNewEmployee = cmdb.newCard("Employee")
  .withCode("T1000")
  .with("Name", "James")
  .withAttribute("Surname", "Hetfield")
  .create();

ExistingCard​

Builders​

  • existingCard(String className, Long id) — ExistingCard
    Creates a Card existing in the specified Class having the specified Id to query CMDBuild

  • existingCard(CardDescriptor cardDescriptor) — ExistingCard
    Creates an existing Card indicated by the specified CardDescriptor to query CMDBuild

Modifiers​

  • withCode(String value) — ExistingCard
    Sets the Code for the Card requested to CMDBuild

  • withDescription(String value) — ExistingCard
    Sets the Description for the Card requested to CMDBuild

  • with(String name, Object value) — ExistingCard
    Sets the specified attribute with the specified value for the Card requested to CMDBuild

  • withAttribute(String name, Object value) — ExistingCard
    Sets the specified attribute with the specified value for the Card requested to CMDBuild

  • withAttachment(String url, String name, String category, String description) — ExistingCard
    Attaches a file (pointed out through a server local URL) to the selected Card by setting the file name, its category and its description

  • attachments() — ExistingCard
    Allows access to the attachments of the selected Card

  • selectAll() — ExistingCard
    Allows to select all documents of the selected Card

  • selectByName(String name1, String name2, ...) — ExistingCard
    Allows to select documents of the selected Card by the specified names

Actions​

  • update() — void
    Updates the Card in CMDBuild by setting the previously specified attributes and values

  • delete() — void
    Deletes the Card from CMDBuild; if the attachments modifier has been used, it will delete only the selected files

  • fetch() — Card
    Requests the Card from CMDBuild with the previously specified attributes. If no modifier has been used, it requests the whole Card (with all attributes)

  • fetch() — Iterable<AttachmentDescriptor>
    If the attachments modifier has been used, the method returns the list of the Card attachments

  • upload(Attachment attachment, Attachment attachment2, ...) — void
    To be used in the presence of the attachments modifier: attaches one or more files to the Card

  • upload(Attachment attachment, String description, String category, String url) — void
    To be used in the presence of the attachments modifier: attaches to the Card a single file with specified description and category

  • download() — Iterable<Attachment>
    If the attachments modifier has been used, the method returns the selected attachments of the Card

  • copyTo() — void
    If the attachments modifier has been used, the method copies a selected attachment of the Card into a specified destination

  • copyToAndMerge() — void
    If the attachments modifier has been used, the method copies a selected attachment of the Card into a specified destination or skips this action if the attachment already exists

  • moveTo() — void
    If the attachments modifier has been used, the method moves a selected attachment of the Card into a specified destination

  • moveToAndMerge() — void
    If the attachments modifier has been used, the method moves a selected Card attachment into a specified destination or skips this action if the attachment already exists

[Examples:]

/*
  * It modifies the card previously created in the class "Employee"
  * by setting the following attributes:
  * "Phone" = "754-3010"
  * "Email" = "<j.hetfield@somemail.com>"
  */
cmdb.existingCard(cdNewEmplyee)
.with("Phone", "754-3010")
.withAttribute("Email", "j.hetfield@somemail.com")
.update();

/*
  * (Logic) delete of the card previously created in the class
  * "Emplyoee"
  */
cmdb.existingCard(cdNewEmplyee).delete();

/*
  * Delete of the card attachment that was previuosly
  * created in the "Employee" class
  */

Iterable \<AttachmentDescriptor\> attachments =
cmdb.existingCard(cdNewEmplyee)
.attachments()
.fetch();

/*
  * Delete of the card attachment that was previuosly
  * created in the "Employee" class
  */

cmdb.existingCard(cdNewEmplyee)
.attachments()
.selectByName(String\[\]`{\"attachment-name\"}`)
.delete();

NewProcessInstance​

Builders​

  • newProcessInstance(String processClassName) — NewProcessInstance
    Creates a new process instance in CMDBuild for the specified process

Modifiers​

  • withDescription(String value) — NewProcessInstance
    Adds the Description to the new process created in CMDBuild

  • with(String name, Object value) — NewProcessInstance
    Adds the specified value for the specified attribute to the new process created in CMDBuild

  • withAttribute(String name, Object value) — NewProcessInstance
    Adds the specified value for the specified attribute to the new process created in CMDBuild

Actions​

  • start() — ProcessInstanceDescriptor
    Creates the new process in CMDBuild with the previously defined attributes, without advancing

  • startAndAdvance() — ProcessInstanceDescriptor
    Creates the new process in CMDBuild with the previously defined attributes and advances to the next step

Example

/*
  * Creation of a new card in the "RequestForChange" class
  * having the following attributes
  * "Requester" = "James Hetfield"
  * "RFCExtendedDescription" = "My printer is broken"
*/

pidNewRequestForChange = 
  cmdb.newProcessInstance("RequestForChange")
    .with("Requester", "James Hetfield")
    .withAttribute("RFCExtendedDescription", "My printer is broken")
    .startAndAdvance();

ExistingProcessInstance​

Builders​

  • existingProcessInstance(String processClassName, int processId) — ExistingProcessInstance
    Creates a process instance existing in the specified process class with the specified Id

Modifiers​

  • withProcessInstanceId(String value) — ExistingProcessInstance
    Sets the process instance Id

  • with(String name, Object value) — ExistingProcessInstance
    Sets the specified attribute with the specified value for the process instance

  • withAttribute(String name, Object value) — ExistingProcessInstance
    Sets the specified attribute with the specified value for the process instance

  • withDescription(String value) — ExistingProcessInstance
    Sets the Description for the process instance

  • attachments() — Attachments
    Allows access to the attachments of the process instance

Actions​

  • abort() — void
    Aborts the process instance

  • advance() — void
    Advances the process instance

  • resume() — void
    Resumes the hanging process instance

  • suspend() — void
    Suspends the open process instance

  • update() — void
    Updates the process instance

Example

/*
  * Update of the process instance in the class "Request
  * for change" with Id = pid by editing the requester and
  * advancing the process at the following step
*/

cmdb.existingProcessInstance("RequestForChange", pid)
  .with("Requester", cdNewEmployee.getId())
  .advance();

NewRelation​

Builders​

  • newRelation(String domainName) — NewRelation
    Creates a new relation in the specified Domain of CMDBuild

Modifiers​

  • withCard1(String className, int cardId) — NewRelation
    Sets the card on the source side of the relation

  • withCard2(String className, int cardId) — NewRelation
    Sets the card on the target side of the relation

  • withAttribute(String attributeName, Object attributeValue) — NewRelation
    Sets the value of a relation attribute

Actions​

  • create() — void
    Creates the new relation in CMDBuild among the Cards indicated in the specified Domain

Example

/*
  * Creation of a new relation in the "AssetAssignee" domain
  * between a card of the selected "Asset" class,
  * through the "Item" Reference attribute, and
  * the card previously created in the "Employee" class
*/

cmdb.newRelation("AssetAssignee")
  .withCard1("Employee", cdNewEmployee.getId())
  .withCard2("Asset", Item.getId())
  .create();

ExistingRelation​

Builders​

  • existingRelation(String domainName) — ExistingRelation
    Creates an existing relation in the specified Domain of CMDBuild

Modifiers​

  • withCard1(String className, int cardId) — ExistingRelation
    Sets IdClass and the ObjId of the Card from the source side of the relation

  • withCard2(String className, int cardId) — ExistingRelation
    Sets IdClass and the ObjId of the Card from the target side of the relation

Actions​

  • delete() — void
    Deletes the relation existing among the Cards indicated in the specified Domain

Example

/*
  * Delete the relation on the "AssetAssignee" domain
  * among the cards previously indicated
*/

cmdb.existingRelation("AssetAssignee")
  .withCard1("Employee", cdNewEmployee.getId())
  .withCard2("Asset", Item.getId())
  .delete();

QueryClass​

Builders​

  • queryClass(String className) — QueryClass
    Creates a query that targets the specified Class in CMDBuild

Modifiers​

  • withCode(String value) — QueryClass
    Sets the Card Code used as a filter for the CMDBuild query

  • withDescription(String value) — QueryClass
    Sets the Card Description used as a filter for the CMDBuild query

  • with(String name, Object value) — QueryClass
    Sets the value of the specified Card attribute for the query filter

  • withAttribute(String name, Object value) — QueryClass
    Sets the value of the specified Card attribute for the query filter

Actions​

  • fetch() — List<Card>
    Performs the search query on the specified Class of CMDBuild and returns the list of those Cards that respect the previously defined filter

Example

/*
  * List of the cards of the "Employee" class having
  * the "State" attribute set to 'Active'
*/

Employees = cmdb.queryClass("Employee")
  .with("State", "Active")
  .fetch();

QueryLookup​

Builders​

  • queryLookup(String type) — QueryAllLookup
    Creates a query that targets the specified Lookup type in CMDBuild

Actions​

  • fetch() — Iterable<Lookup>
    Performs the search query on the specified Lookup type of CMDBuild and returns the list of those Lookups

CallFunction​

Builders​

  • callFunction(String functionName) — CallFunction
    Creates a call to a stored procedure previously defined in PostgreSQL

Modifiers​

  • with(String name, Object value) — CallFunction
    Sets the value of the specified input parameter for the stored procedure

Actions​

  • execute() — Map<String, Object>
    Performs the stored procedure and returns the list of the output parameters with the related values

Example

/*
  * Call of the stored PostgreSQL procedure
  * "cmwf_getImpact"(IN "DeliveryDate" date, IN "Cost" integer,
  * OUT "Impact" character varying)
  * that computes the impact level (attribute of
  * "Impact" process) of an activity on a scale of "High",
  * "Medium" and "Low", given in input the expected delivery
  * date (process attribute "ExpectedDeliveryDate") and
  * the price (attribute "ManHoursCost") expressed in hour/employee
*/

spResultSet = cmdb.callFunction("cmwf_getImpact")
  .with("DeliveryDate", ExpectedDeliveryDate.getTime())
  .with("Cost", ManHoursCost)
  .execute();

Impact = spResultSet.get("Impact")

Note: SQL functions - which should be called - must be defined according to CMDBuild standards. For their definition, see the Administrator Manual, section Cart TAB, paragraph "Definition of the data source (PostgreSQL function)".

QueryRelations​

Builders​

  • queryRelations(CardDescriptor cardDescriptor) — ActiveQueryRelations
    Creates a query to ask CMDBuild the Cards related to the specified one

  • queryRelations(String className, long id) — ActiveQueryRelations
    Creates a query to ask CMDBuild the Cards related to that specified by className and id

Modifiers​

  • withDomain(String domainName) — ActiveQueryRelations
    Sets the Domain to perform the query

Actions​

  • fetch() — List<CardDescriptor>
    Performs the query on CMDBuild using the previously defined parameters and returns the list of the linked Cards

Example

/*
  * List of "Assets" linked to the "Employee" card indicated
  * by the CardDescriptor cdNewEmployee previously created,
  * through the relation on the domain "AssetAssignee"
*/

assets = cmdb.queryRelation(cdNewEmployee)
  .withDomain("AssetAssignee")
  .fetch();

CreateReport​

Builders​

  • createReport(String title, String format) — CreateReport
    Creates the Report in the specified format (pdf, csv) with the specified Title

Modifiers​

  • with(String name, Object value) — CreateReport
    Sets the input parameter value specified for the Report

Actions​

  • download() — DownloadedReport
    Generates the indicated Report using the previously defined parameters

Example

/*
  * It generates the Report "DismissedAssets" which shows the list
  * of the abandoned Assets
*/

newReport = cmdb.createReport("Assigned assets to")
  .download();

NewMail​

Builders​

  • newMail() — NewMail
    Creates a new e-mail to send

Modifiers​

  • withFrom(String from) — NewMail
    Sets the sender of the e-mail to send

  • withTo(String to) — NewMail
    Sets the recipient of the e-mail to send

  • withTo(String... tos) — NewMail
    Sets the recipients of the e-mail to send

  • withTo(Iterable<String> tos) — NewMail
    Sets the recipients of the e-mail to send

  • withCc(String cc) — NewMail
    Sets the carbon copy recipient of the e-mail to send

  • withCc(String... ccs) — NewMail
    Sets the carbon copy recipients of the e-mail to send

  • withCc(Iterable<String> ccs) — NewMail
    Sets the carbon copy recipients of the e-mail to send

  • withBcc(String bcc) — NewMail
    Sets the blind carbon copy recipient of the e-mail to send

  • withBcc(String... bccs) — NewMail
    Sets the blind carbon copy recipients of the e-mail to send

  • withBcc(Iterable<String> bccs) — NewMail
    Sets the blind carbon copy recipients of the e-mail to send

  • withSubject(String subject) — NewMail
    Sets the subject of the e-mail to send

  • withContent(String content) — NewMail
    Sets the text of the e-mail to send

  • withContentType(String contentType) — NewMail
    Sets the content MimeType of the e-mail to send, the allowed values are "text/html" or "text/plain". If not otherwise specified, the default value is "text/plain"

  • withAttachment(URL url) — NewMail
    Sets the url of a document to enclose to the e-mail

  • withAttachment(String url) — NewMail
    Sets the url (as a string) of a document to enclose to the e-mail

  • withAttachment(URL url, String name) — NewMail
    Sets the url of a document with the specified name to enclose to the e-mail

  • withAttachment(String url, String name) — NewMail
    Sets the url (as a string) of a document to enclose to the e-mail with a specified name

  • withAttachment(DataHandler dataHandler) — NewMail
    Sets the dataHandler as an attachment of the e-mail

  • withAttachment(DataHandler dataHandler, String name) — NewMail
    Sets the dataHandler as an attachment with the specified name

  • withCard(@Nullable String className, @Nullable Long cardId) — NewMail
    Sets the card related to the email

  • withCard(@Nullable CardDescriptor card) — NewMail
    Sets the card related to the email

  • withCard(@Nullable ReferenceType card) — NewMail
    Sets the card related to the email

  • withAsynchronousSend(bool boolean) — NewMail
    Sends the e-mail asynchronously in spite of the script; in this way any timeout problem will be avoided, but you will not be able to intervene in case of error by sending the e-mail

Actions​

  • send() — void
    Performs the e-mail sending using the previously defined statements

Example

/*
  * Send a new email
*/

cmdb.newMail()
  .withFrom("<fromaddress@somemail.com>")
  .withTo("<toaddress@somemail.com>")
  .withCc("<ccaddress@somemail.com>")
  .withSubject("Mail subject")
  .withContent("Mail content")
  .send();

Methods for types conversion​

The following methods are utility functions available via the cmdb object. They allow conversion between different CMDBuild data types, such as obtaining a ReferenceType from a Card, or a LookupType from a code or description.

ReferenceType​

  • referenceTypeFrom(Card card) — ReferenceType Returns the ReferenceType item related to the specified Card

  • referenceTypeFrom(CardDescriptor cardDescriptor) — ReferenceType Returns the ReferenceType item related to the specified CardDescriptor

  • referenceTypeFrom(long id) — ReferenceType Returns the ReferenceType item related to the card with the specified Id

Example

/*
  * Set the "Requester" process attribute Reference
  * type, given the "cdNewEmployee" CardDescriptor
  * previously created
*/

Requester = cmdb.referenceTypeFrom(cdNewEmployee);

LookupType​

  • selectLookupById(long id) — LookupType
    Returns the LookupType item with the specified Id

  • selectLookupByCode(String type, String code) — LookupType
    Returns the LookupType item with the specified Type and Code

  • selectLookupByDescription(String type, String description) — LookupType
    Returns the LookupType item with the specified Type and Description

Example

/* 
  * Set the "State" process attribute Lookup type having:
  * "Type" = "Employee state"
  * "Code" = "ACTIVE"
*/

State = cmdb.selectLookupByCode("Employee state", "ACTIVE");

CardDescriptor​

  • cardDescriptorFrom(ReferenceType reference) — CardDescriptor
    Returns the CardDescriptor of the specified card through the specified ReferenceType item

  • cardDescriptorFrom(long id) — CardDescriptor
    Returns the CardDescriptor of the specified card through the specified Id

Example

/*
  * Get the CardDescriptor related to the "Requester"
  * process attribute Reference type
*/

cdSelectedEmployee = cmdb.cardDescriptorFrom(Requester);

Card​

  • cardFrom(ReferenceType reference) — Card
    Returns the Card item of the specified card through the specified ReferenceType item

Example

/*
  * Get the complete Card related to the "Requester"
  * process attribute Reference type
*/

selectedEmployee = cmdb.cardFrom(Requester);