View Source

In this tutorial you will learn by example how to setup a rule to lookup data from your JIRA server and set it to ConfiForms fields

Let's start with a simple form

It will have just 3 fields

A field (called "keyCF") to ask for JIRA key (can be of any type, as long as the value it holds is a JIRA key, as we will use it to make lookups)
ConfiForms field (called "reporterCF") to hold Reporter name (reporter username in JIRA)
ConfiForms field (called "summaryCF") to hold Issue summary

For clarity we name our ConfiForms fields with postfix "CF"

The form looks like this in view mode:

ConfiForms > Using Field Definition Rule to request data from JIRA and set it to ConfiForms fields > image2016-9-27 10:51:41.png

Same form in edit mode:

ConfiForms > Using Field Definition Rule to request data from JIRA and set it to ConfiForms fields > image2016-9-27 10:52:25.png

And it's storage format

<ac:structured-macro ac:macro-id="0ac060cf-c01e-4b08-bccf-6ecba9bc13a2" ac:name="confiform" ac:schema-version="1">
  <ac:parameter ac:name="formName">f</ac:parameter>
  <ac:rich-text-body>
    <ac:structured-macro ac:macro-id="ffda1fef-a7fc-4eda-8659-ef0107f79012" ac:name="confiform-entry-register" ac:schema-version="1">
      <ac:parameter ac:name="embedded">true</ac:parameter>
      <ac:rich-text-body>
        <p> </p>
      </ac:rich-text-body>
    </ac:structured-macro>
    <p>
      <ac:structured-macro ac:macro-id="e09ebd7b-dde0-4a2b-8b81-aa6d41f703ac" ac:name="confiform-field-definition" ac:schema-version="1">
        <ac:parameter ac:name="css">max-width:100px;width:100px;</ac:parameter>
        <ac:parameter ac:name="fieldName">keyCF</ac:parameter>
        <ac:parameter ac:name="fieldLabel">JIRA ticket #</ac:parameter>
        <ac:parameter ac:name="fieldDescription">projectkey-000</ac:parameter>
        <ac:parameter ac:name="type">text</ac:parameter>
      </ac:structured-macro>
    </p>
    <p>
      <ac:structured-macro ac:macro-id="4371f87c-8e6d-4b7f-9d6b-f1f9b71f66f6" ac:name="confiform-field-definition-rules" ac:schema-version="1">
        <ac:parameter ac:name="condition">!keyCF:[empty]</ac:parameter>
        <ac:parameter ac:name="fieldName">reporterCF=fields.reporter.name&amp;summaryCF=fields.summary</ac:parameter>
        <ac:parameter ac:name="values">[entry.keyCF]</ac:parameter>
        <ac:parameter ac:name="action">Lookup and set JIRA issue data</ac:parameter>
        <ac:parameter ac:name="actionFieldName">keyCF</ac:parameter>
        <ac:parameter ac:name="values2">JIRA</ac:parameter>
      </ac:structured-macro>
    </p>
    <p>
      <ac:structured-macro ac:macro-id="36f3ebd8-aa8e-458a-bf0d-78a8cf672b6b" ac:name="confiform-field-definition" ac:schema-version="1">
        <ac:parameter ac:name="fieldName">reporterCF</ac:parameter>
        <ac:parameter ac:name="fieldLabel">Reporter field from JIRA</ac:parameter>
        <ac:parameter ac:name="type">text</ac:parameter>
      </ac:structured-macro>
    </p>
    <p>
      <ac:structured-macro ac:macro-id="20302f9b-ba51-4aeb-bb65-e5adffdb09bf" ac:name="confiform-field-definition" ac:schema-version="1">
        <ac:parameter ac:name="fieldName">summaryCF</ac:parameter>
        <ac:parameter ac:name="fieldLabel">Summary</ac:parameter>
        <ac:parameter ac:name="type">text</ac:parameter>
      </ac:structured-macro>
    </p>
  </ac:rich-text-body>
</ac:structured-macro>

The most interesting bit is the definition rule itself

     <ac:structured-macro ac:macro-id="4371f87c-8e6d-4b7f-9d6b-f1f9b71f66f6" ac:name="confiform-field-definition-rules" ac:schema-version="1">
        <ac:parameter ac:name="condition">!keyCF:[empty]</ac:parameter>
        <ac:parameter ac:name="fieldName">reporterCF=fields.reporter.name&amp;summaryCF=fields.summary</ac:parameter>
        <ac:parameter ac:name="values">[entry.keyCF]</ac:parameter>
        <ac:parameter ac:name="action">Lookup and set JIRA issue data</ac:parameter>
        <ac:parameter ac:name="actionFieldName">keyCF</ac:parameter>
        <ac:parameter ac:name="values2">JIRA</ac:parameter>
      </ac:structured-macro>

Or in the macro editor:

ConfiForms > Using Field Definition Rule to request data from JIRA and set it to ConfiForms fields > image2016-9-27 10:53:59.png

So, we setup a rule to be executed when "keyCF" field value changes and will execute it when the condition is met and that means when a field has some value (is not empty)

(macro configuration continues)

ConfiForms > Using Field Definition Rule to request data from JIRA and set it to ConfiForms fields > image2016-9-27 10:57:5.png

As action we select "Lookup and set JIRA issue data" and it will take the value for JIRA lookup from "keyCF"

And the most important bit is "Values to set" parameter and how the JIRA issue data is mapped to ConfiForms fields

reporterCF=fields.reporter.name&summaryCF=fields.summary

reporterCF and summaryCF are ConfiForms fields

and "fields.reporter.name" and "fields.summary" are fields form JIRA

As the integration between ConfiForms and JIRA is done using JIRA REST API (through application links) - we work on a JSON served by JIRA

Here is an example JSON served by JIRA

ConfiForms > Using Field Definition Rule to request data from JIRA and set it to ConfiForms fields > image2016-9-27 11:4:52.png

To access "reporter's username" You will need to navigate the JSON using the following syntax "fields.reporter.name"

You can navigate any field from the served JSON, including custom fields and complex fields (such as user objects, watches, etc).

Couple of examples:

Finding what

Structure

Syntax

assignee email

ConfiForms > Using Field Definition Rule to request data from JIRA and set it to ConfiForms fields > image2016-9-27 11:9:11.png

fields.assignee.emailAddress

issue summary

fields.summary

Status name

ConfiForms > Using Field Definition Rule to request data from JIRA and set it to ConfiForms fields > image2016-9-27 11:13:47.png

fields.status.name

Status color

ConfiForms > Using Field Definition Rule to request data from JIRA and set it to ConfiForms fields > image2016-9-27 11:14:30.png

fields.status.statusCategory.colorName

Issue key

ConfiForms > Using Field Definition Rule to request data from JIRA and set it to ConfiForms fields > image2016-9-27 11:16:56.png

key

(not fields.key! as it is under the JSON root, not under "fields", see the main screenshot with JIRA issue data)

This is it, the tutorial ends here but your joerney with ConfiForms just begins! Welcome and if you have any questions feel free to ask and share your feedback/concerns