Page tree

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 32 Next »

This is the documentation for ConfiForms Server/Data Center app

However, this might also work for ConfiForms cloud and in most cases it does. But please see this page to understand the differences between server and cloud versions of the ConfiForms app.


In order to make it easier to integrate with other external systems, such as JIRA, for example, we have implemented so called "virtual" functions, what you can call on field values.

 

Usage:

  • When using in IFTTT macro body or in ListView/PlainView/CalendarView - the notation would be: [entry.fieldname.virtual_function] 

 

  • When using in ConfiForms Field macro then reference it by fieldname, adding the virtual function name: fieldname.virtual_function

 

Useful, when you try to prepare a JSON or some other format when used together with IFTTT macro to enable integrations with other systems

 

See also Accessing field values and properties. You can use complex properties in your filters. For example filtering dropdown fields by values and by labels, filtering page type fields by page metadata fields, filtering user fields by, for example - email property


As of now, the following functions are supported:

FunctionDescriptionUsing in ConfiForms Field macroUsing in ListVIew/PlanView/CalendarView or in IFTTT macro body
urlencode

Does URL encode on given value, see "urlEncode" method in

https://developer.atlassian.com/static/javadoc/confluence/4.0/reference/com/atlassian/confluence/util/GeneralUtil.html

myfield.urlencode[entry.myfield.urlencode]
escapeXML

Escapes XML on given value, see "escapeXml" method in

https://developer.atlassian.com/static/javadoc/confluence/4.0/reference/com/atlassian/confluence/util/GeneralUtil.html

myfield.escapeXml[entry.myfield.escapeXml]
escape

Escapes string as in "escapeForHtmlAttribute" method in

https://developer.atlassian.com/static/javadoc/confluence/4.0/reference/com/atlassian/confluence/util/GeneralUtil.html

myfield.escapeForHtmlAttribute[entry.myfield.escapeForHtmlAttribute]
formatDate
Tries to format date fields in the specified format, expects date format as in http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.htmlmyfield.formatDate(JAVA_FORMAT)

[entry.myfield.formatDate(JAVA_FORMAT)]

(no quotes)

jiraDate
Same as "formatDate" method above, but specifies constant dateformat pattern (yyyy-MM-dd), suitable for JIRA REST APImyfield.jiraDate[entry.myfield.jiraDate]
jiraDateTime
Same as "formatDate" method above, but specifies constant dateformat pattern ("yyyy-MM-dd'T'HH:mm:ss.SSSZ"), should be compatible with ISO 8601 standard as JIRA requires when setting timestamps to JIRA fieldsmyfield.jiraDateTime[entry.myfield.jiraDateTime]
escapeJSON
Escapes illegal characters in the field value to generate a valid JSON property. New lines, quotes, tabs and etc will be properly escapedmyfield.escapeJSON[entry.myfield.escapeJSON]
asArray
asArrayMultiSelect
asArrayMultiUserPicker

 

Tries to create an array from the value. Useful when you want to pass ConfiForms multi-select values to JIRA. Something like

"customfield_XXXX" : [[entry.myfield.asArray]]
 
this will generate
 
"customfield_XXXX" : ["val1","val2"]
 
assuming "myfield" field is a multi select and has 2 values: val1 and val2

 

There are variations to support other multi-select fields in JIRA

https://developer.atlassian.com/jiradev/jira-apis/jira-rest-apis/jira-rest-api-tutorials/jira-rest-api-example-create-issue#JIRARESTAPIExample-CreateIssue-MultiSelect

  • asArrayMultiSelect
  • asArrayMultiUserPicker (can be used to generate arrays for both: multi-user and multi-group field types)

 

myfield.asArray

myfield.asArrayMultiSelect

myfield.asArrayMultiUserPicker

[entry.myfield.asArray]

[entry.myfield.asArrayMultiSelect]

 [entry.myfield.asArrayMultiUserPicker]

asArrayOfIds

Same as the above, but exporting IDs of the multi-select values in the following format:

"1", "2"
myfield.asArrayOfIds[entry.myfield.asArrayOfIds]
replaceCRLFWithBR
Replaces CR/LF with <BR/> to show with line brakes in HTML (useful when you reference the textarea field using [entry.] notation)myfield.replaceCRLFWithBR[entry.myfield.replaceCRLFWithBR]
asUserFullNames
Works only with User multi-select fields and shows list of full names for selected usersmyfield.asUserFullNames[entry.myfield.asUserFullNames]
asUserEmails
Works only with User multi-select fields and shows list of emails for selected usersmyfield.asUserEmails[entry.myfield.asUserEmails]
asUserNames
Works only with User multi-select fields and shows list of usernames for selected usersmyfield.asUserNames[entry.myfield.asUserNames]
friendlyDate
Formatting date and date/time field types with https://docs.atlassian.com/confluence/latest/com/atlassian/confluence/core/datetime/FriendlyDateFormatter.htmlmyfield.friendlyDate[entry.myfield.friendlyDate]
asCount
Returns size of a collection for multi-value fields or number of chars for other typesmyfield.asCount[entry.myfield.asCount]
asSize
Returns size of a collection for multi-value fields or number of chars for other types (same as "count")myfield.asSize[entry.myfield.asSize]
asLength
Returns size of a collection for multi-value fields or number of chars for other typesmyfield.asLength[entry.myfield.asLength]
formatCurrency

 

Tries to format value as currency using either default or given format

https://docs.oracle.com/javase/7/docs/api/java/text/DecimalFormat.html

If value could not be formatted according to given format then value will be returned as is

Can be used with any number (and not only currency)

myfield.formatCurrency(JAVA_FORMAT)

myfield.formatCurrency()

(default decimal format is used if empty)

[entry.myfield.formatCurrency(JAVA_FORMAT)]

(no quotes, JAVA_FORMAT could be empty, default will be used)

 

[entry.myfield.formatCurrency(# ###.##)]

[entry.myfield.formatCurrency(# ###.00)]

formatNumber
alias to formatCurrency

myfield.formatNumber(JAVA_FORMAT)

myfield.formatNumber()

(default decimal format is used if empty)

[entry.myfield.formatNumber(JAVA_FORMAT)]

[entry.myfield.formatNumber(# ###.##)]

[entry.myfield.formatNumber(# ###.00)]

asFilteredBy(FILTER)

Very powerful function to extract the value by given filter (mostly used for multi-value fields).

Especially useful with Multi-select fields which are of type "smart fields", the ones referencing other forms and fields

Example:

You have one form which has a field called "mf" which holds multi-value references to another form which has the following fields: name, surname, position

Then... when showing the data from the first form you can actually show only specific choices.

For example:

  • entry.mf.asFilteredBy(name:Alex) - to show only persons selected with name Alex only (here "name" references a field in 2nd form)
  • entry.mf.asFilteredBy(surname:Ve*) - to show only persons selected with surnames starting with "Ve" only (here "surname" references a field in 2nd form)
  • entry.mf.asFilteredBy(position:CEO) - to filter OUT all those selected who are NOT in CEO position
entry.mf.asFilteredBy(FILTER)

Filter should be in a format:

property:filter

[entry.mf.asFilteredBy(name:Alex)]

The following filters are supported:

  • value*
  • *value
  • *value*
  • *
  • [empty]

 

trimAllSpaces

Removes all the spaces in the field value.

Can be used when creating page labels automatically from ConfiForms field values and want to ensure the value is taken as a label and not split by spaces into differenet labels

entry.myfield.trimAllSpaces[entry.myfield.trimAllSpaces]
camelCase
Makes a CamelCase string from a given valueentry.myfield.camelCase[entry.myfield.camelCase]
camelCaseAndTrim
Makes a CamelCase string from a given value and, additionally, removes all the spacesentry.myfield.camelCaseAndTrim[entry.myfield.camelCaseAndTrim]
addCRLFAdds CR and LF characters after the valueentry.addCRLF[entry.addCRLF]
addCRLFHtmlAdds <br/> (brake) after the value in HTML formatentry.addCRLFHtml[entry.addCRLFHtml]
trunc(NUMBER)Truncates the value. Leaves "n" first symbolsentry.trunc(100)[entry.trunc(100)]

asAttachment

asAttachment(n)

You can reference a particular attachment stored in Confluence and linked though ConfiForms Field (either File or Attachment picker)

n - is the index of the attachment stored/linked using ConfiForms Field. Index starts with 0. When no index is specified, then the 1st attachment is taken (1st attachment is stored with index 0)

This means that

asAttachment = asAttachment(0)

This function is a "bridge" to get other properties of the attachment stored. See below.

entry.asAttachment

[entry.asAttachment]

[entry.asAttachment(0)]

[entry.asAttachment(1)]

asAttachment.base64

asAttachment(1).base64

Returns bas64 encoded string of the file contents in this attachmententry.asAttachment.base64

[entry.asAttachment.base64]

[entry.asAttachment(0).base64]

[entry.asAttachment(1).base64]

asAttachment.ANY_PROPERTY

asAttachment(n).ANY_PROPERTY

 

Where ANY_PROPERTY is the "get" methods of the class Attachment https://docs.atlassian.com/confluence/5.9.1/com/atlassian/confluence/pages/Attachment.html

Examples:

asAttachment.displayTitle
asAttachment.id
asAttachment.downloadPath
asAttachment.contentType 
 
and many other properties of the Attachment object
 
asAttachment(1).displayTitle - also perfectly valid and will try to get the display title for the attachment stored "second" in the field
  

asUser.username

asUser.fullName

asUser.email

asUser(n).username

asUser(n).fullName

asUser(n).email

 When working with multi-select user control/field and want to get a particular user info

Only works with Multi-select user field!

  
asEntryRef(REF_TO_ENTRY)

Example:

[entry.id.asEntryRef(entry.id)]

This will return

[entry.id]

When this is necessary?

The use case is when you use it within an IFTTT or have a ListView which has another ListView inside and you want to prevent ConfiForms from applying the context variables onto the sub-lists

 

The function can be used with any field type (as long as the field exists) and actually the following constructions are perfectly valid

[entry.id.asEntryRef(entry.somefield)] will return [entry.somefield]
[entry.id.asEntryRef(entry.mytextfield)] will return [entry.mytextfield]
[entry.id.asEntryRef(entry.anotherfield)] will return [entry.anotherfield]
[entry.id.asEntryRef(entry.id)] will return [entry.id]

 

As you can see we apply the function on the same ID field (exists in every ConfiForms record) and the parameter you give in is the important bit in all this...

So, the parameter (PARAM) you give to asEntryRef is wrapped into the brackets and returned:

[PARAM]

 

 

  
asJSONConverts a value to JSON and allows to access JSON object properties

entry.myfield.asJSON.someJSONProperty

entry.myfield.asJSON.anotherJSONProperty

 
asUserProfile

Converts to User profile (or tries to, if a given field value can be resulved as a user object)

Available user profile properties (all standard ones, available in the profile) to reference are:

  • phone
  • im
  • website
  • position
  • department
  • location

entry.somefield.asUserProfile.phone

entry.somefield.asUserProfile.im

entry.somefield.asUserProfile.website

entry.somefield.asUserProfile.position

entry.somefield.asUserProfile.department

entry.somefield.asUserProfile.location

 

where "somefield" should get resolved into username (can be user field)

[entry.somefield.asUserProfile.phone]

[entry.somefield.asUserProfile.im]

[entry.somefield.asUserProfile.website]

[entry.somefield.asUserProfile.position]

[entry.somefield.asUserProfile.department]

[entry.somefield.asUserProfile.location]

asListExtracts values of a list and converts to a comma-separated string, see below for examples on transform and asList  
asAttachments

Converts the file/attachment field values into the array of Attachment objects

https://docs.atlassian.com/confluence/5.9.1/com/atlassian/confluence/pages/Attachment.html

  
transform(property_name)

Converts the list of some objects into the list of values for the given property

For example:

[entry.myfile.asAttachments.transform(id)]

When "myfile" is a field of type file/attachment, a function "asAttachments" will convert it's values into the list of Attachments objects and then function "transform" will extract and "id" property of each Attachment object and will put it into the resulting list

[entry.myfile.asAttachments.transform(id).asList]

Same as in previous example, but we convert the otput into a comma separated list of attachment IDs

Below, is another example, which returns a result of ID's, but wrapped into quotes

[entry.myfile.asAttachments.transform(id).asArray]

 

Function "transform" can be used on a multi-value field.

For example, to get the list of dropdown IDs

[entry.mymultifield.transform(id)]

 

To get the list of dropdown labels

[entry.mymultifield.transform(label)]

To get the list of User's full names for multi-user field

[entry.mymultiuserfield.transform(fullName)]

same as above, but in "coma-separated" string

[entry.mymultiuserfield.transform(fullName).asList]
  

If entry value is null or could not be formatted according to rules then value is returned as-is 

See also Accessing field values and properties. You can use complex properties in your filters. For example filtering dropdown fields by values and by labels, filtering page type fields by page metadata fields, filtering user fields by, for example - email property

 

It is important to understand that it is absolutely possible to combine virtual functions WITH field properties

 

(JAVA_FORMAT)

  • No labels