ConfiForms

Space shortcuts

Expand all   Collapse all
Child pages
  • Using Field Definition Rule to request data from JIRA and set it to ConfiForms fields

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

If you are new to ConfiForms, please take a few minutes to read the Basic concepts Guide, or go through the video tutorial on that page.  (smile)

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:

Same form in edit mode:

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:

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)

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

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 whatStructureSyntax
assignee email
fields.assignee.emailAddress
issue summary 
fields.summary
Status name
fields.status.name
Status color
fields.status.statusCategory.colorName
Issue key
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

 

 

 

  • No labels