How do expand panels work in jira cloud

Hi we are working on a integration that uses the jira cloud api (previously using jira server) and we have are facing a problem understanding how a certain macro/feature of the new editor works.

When using the expand macro the result we see in the api looks like this:

*Expand Title*\n\nExpand body

and the result when we use expand=renderedFields to have a HTML output

<p><b>Expand Title</b></p>\n\n<p>Expand body</p>

Now this looks odd and we are uncertain what other endpoint/param we need to get a deterministic answer since this looks the same as having a bold text followed by a normal paragraph ( as we can see in the html output/description field of the issue.

all the other new features seem to be clear expect this one and i could not find anything in this forum / any documentation

kind regards
Paul

Hi @paul ,

If you use curl to query the API, you should see that the body of the expand is surrounded by two line feeds, i.e. \n\n.

Unfortunately, however, I’m not aware of any documentation of this format.

Regards,
Dugald

Hi @dmorrow,

I think i figured out how this works. jiracloud uses the /rest/api/3/ which seems to be in beta which has some special syntax:

"description": {
            "version": 1,
            "type": "doc",
            "content": [
                {
                    "type": "expand",
                    "attrs": {
                        "title": "Expand Title"
                    },
                    "content": [
                        {
                            "type": "paragraph",
                            "content": [
                                {
                                    "type": "text",
                                    "text": "expand body"
                                }
                            ]
                        }
                    ]
                }
            ]
        },

If anyone figures out a way to be able to get → identify → post it with an older API please let me know

regards
paul

Hi @PaulHaller ,

The V3 API is based on Atlassian Document Format (ADF), but for reasons such as limited parsing support, it’s still in beta.

Since your enquiry specifically related to the format returned by the V2 API, and the V3 API is in beta, I didn’t suggest the V3 API as an option.

Does the double line feed delimiter solution I shared above not work?

Regards,
Dugald

Hi @dmorrow,

no the double line is not a unique thing that we can use to identify it in the payload. Also with the v2 endpoint i was not able to post such an element in anyway.

But for our use cases using the v3 API will make things easier in the end for our use case anyway. How likely is that API to still change since it’s in BETA?

thx for the replies

paul

Hi @PaulHaller ,

I spent a bit of time today reproducing this. I was able to retrieve and parse issue descriptions to identify expand macros within it, but I was not able to update issue descriptions with correctly formatted expand macros. Here is my code in case you find it helpful:

import base64 from 'base-64';

interface Expand {
  title: string
  body: string
}

const extractExpandsFromText = (text: string): Expand[] => {
  const expands: Expand[] = [];
  // TODO: The following regex needs work
  const regex = /(\*[A-Za-z0-9\ ]+\*\n\n[A-Za-z0-9\ ]+)/g;
  const matches = text.match(regex);
  console.log(`match = ${JSON.stringify(matches, null, 2)}`);
  if (matches) {
    for (const match of matches) {
      const firstAsteriskIndex = match.indexOf('*');
      const secondAsteriskIndex = match.indexOf('*', firstAsteriskIndex + 1);
      const title = match.substring(firstAsteriskIndex + 1, secondAsteriskIndex);
      const body = match.substring(secondAsteriskIndex + 1).trim();
      const expand: Expand = {
        title: title,
        body: body
      }
      console.log(`Found expand: ${JSON.stringify(expand)}`);
      expands.push(expand);
    }
  }
  return expands;
}

const appendToExpandTitles = (textToAppend: string, expands: Expand[]): void => {
  for (const expand of expands) {
    expand.title += textToAppend;
  }
}

const expandsToText = (expands: Expand[]): string => {
  let text = '';
  for (const expand of expands) {
    text += `*${expand.title}*\n\n${expand.body}\n\n`
  }
  return text;
}

const getIssueDescription = async (): Promise<string> => {
  const url = `${process.env.TENNANT_URL}/rest/api/2/issue/${process.env.ISSUE_KEY}?fields=description`;
  const response = await fetch(url, {
    headers: {
      'Accept': 'application/json',
      'Authorization': `Basic ${base64.encode(`${process.env.API_USERNAME}:${process.env.API_TOKEN}`)}`
    }
  });
  const json = await response.json();
  const description = json.fields.description;
  return description;
}

const setDescription = async (description): Promise<void> => {
  const url = `${process.env.TENNANT_URL}/rest/api/2/issue/${process.env.ISSUE_KEY}`;
  const payload = {
    fields: {
      "description": description
    }
  }
  await fetch(url, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'Authorization': `Basic ${base64.encode(`${process.env.API_USERNAME}:${process.env.API_TOKEN}`)}`
    },
    body: JSON.stringify(payload)
  });
}

setTimeout(async () => {
  const description = await getIssueDescription();
  console.log(`description = ${description}`);
  // const expands = extractExpandsFromText(description);
  // appendToExpandTitles(' foo', expands);
  const newDescription = description;
  await setDescription(newDescription);
});

As a result of this, I’ve created 1. JRACLOUD-81277: Updating an issue description with a expand macro using the V2 REST API corrupts the description.

In the issue I reported, I indicated that using version 3 of the Jira REST API which is based on ADF may not be an acceptable workaround for some developers/partners since this API is still in beta. Having said that, I believe the ADF format should be stable, but may also represent significant work for apps that do a lot of formatting using the V2 API.

Regards,
Dugald

1 Like

Thank you @dmorrow

i will watch the issue you created while we internally consider wether we should change our implementation to use the new API.

1 Like