At the request of some other posters here in the Community, here are some learnings from my first build of a custom Workfront to Jira integration using Fusion. All comments reference Jira Cloud, and reflect my candid, hopefully amusing, learnings from this trial project.
Why did we not use the native Workfront to Jira integration? This article is what I send out to our internal teams when they ask if I’ll configure it for them. https://www.putitforward.com/how-to-integrate-workfront-and-jira#toc-challengeswhenconnectingworkfro... Also: Per Adobe Support, the connection user must be a full admin account and I operate on the principle of least-privilege. Unmonitored accounts should never be administrator level. (That’s my soapbox, and I’m staying on it.)
20/20 Hindsight – What would I do differently?
- Build a bigger POC – When I did my initial feasibility assessment, I thought I’d be able to use the existing connectors included in Fusion that are pre-tested and simple to configure. Ultimately, I needed something more complex that required custom API calls and dramatically increased the build time, complexity and creative vocabulary involved.
- Start smaller – I started with custom request queue forms matching the issue types/fields in Jira and mapped field-to-field. Future expansions will support mapping a list of Workfront fields/inputs into one text box on the Jira issue and allowing the team on that side to complete the form either manually or with their Jira automation tools. This will also avoid future pain when the Jira team change drop-down options and forget to have me update the corresponding options in Workfront.
- Data dictionary: Get a thorough data dictionary built from the Jira side FIRST. Every project, key, issue type, field label, API name, field data type, if it’s required and available values. Some of my technical learnings below would have been completely avoided if I’d started here first.
- Get backup: For future expansions, I've asked to be paired with a peer from the Jira side with more experience in the Jira API to help troubleshoot/QA.
Geeky Technical Stuff:
- Custom fields in Workfront have a configurable Label and a separate API Name. Custom fields in Jira do as well, however only the Label is admin-configurable. The API Name is automatically generated as customfield_###### and is not readily visible anywhere in the Jira UI without JQL trickery to look up each field individually. (At least according to my luck, and our Jira admin. I welcome alternative options.)
- Custom fields in Workfront and Jira will technically allow you to re-use the same Label across multiple fields as long as the API Name is unique. If you don’t already know this, you’ll get stuck in troubleshooting rounds where you fix one field mapping and then break another. If the API Name for the Jira fields was readily visible, I would have picked up on this way sooner.
- Date values in Jira are stored as string data. (Why, Jira, Why?) Trying to insert a date value from Workfront without converting it will generate an error message about the date being required which will make you think you aren’t sending the value, rather than understanding that it’s in the wrong format.
- Both field names and values in drop-downs may have trailing spaces on them. This will cause data mapping to fail unless handled, as “Chocolate Chip Cookies” and “Chocolate Chip Cookies “ are not identical values. Being able to troubleshoot that this error exists requires the admin ability to edit those fields, as the error I got simply said that your input value does not exist.
- Team-managed projects in Jira are different from Company-managed projects. This is a big cause for my notes above regarding identical fields. In a team-managed project, the fields are scoped only to that project and not available elsewhere.
- Jira does not natively support threaded comment/reply functionality like Workfront without the use of additional add-ons that your Jira instance may not allow. This may make porting Workfront Updates/Replies a difficult exercise.
- You’re going to need a process on the Workfront side to map the user IDs for their Jira accounts, if you want the resulting Jira record to know who actually created it rather than only showing the integration user. I'm using a User custom form for my instance.
- If you intend a 2-way sync, you’re going to need to create the integrations link from the Workfront side (easy) and to find a way within Jira to isolate the records created by Workfront with a link back to their record ID in Workfront.
- Setting up the data to be passed properly into the Jira fields requires an understanding of the data types on both sending and receiving sides, JSON syntaxes and some language my Mom would wash my mouth out with soap over. See attachment for the syntax examples I documented for myself as I went through. I'm sure other options exist, these are the variants I needed for my project to work.
@Farzaneh @KIMBERLYREA
