Launch Ironclad Workflow from Jira
# Goal
Allow users to submit an Ironclad workflow in Jira and associate the Ironclad workflow with the Jira issue.
# Overview
This solution pattern (1) enables Jira users to launch Ironclad workflows and (2) associates the new Ironclad workflow with the Jira issue. Workflows are associated with Jira issues by updating the issue with the workflow’s URL and ID and by posting comments in Jira's and Ironclad's respective activity feeds.
<figure>
<img src="https://files.readme.io/d7d81f8-Example_API_Flows_-_Jira__Zapier_Start_Ironclad_Workflow_9.png">
<figcaption>Requests between Jira, Zapier, and Ironclad.</figcaption>
</figure>
# Details
This solution pattern will show how to configure a custom webhook in Jira that triggers a Zapier process to then launch an Ironclad contract workflow. The Zapier process that receives the webhook follows a rule that runs through these steps:
1. Launching an Ironclad workflow using the underlying [Create a Workflow Synchronously](ref:launch-a-new-workflow) endpoint. For a more comprehensive walkthrough of the endpoint, including complex data payloads and limitations, see the [Launch a Workflow](doc:launch-a-workflow) guide.
2. Updating the Jira issue with the workflow’s information.
3. Posting a comment in the Jira issue to confirm successful launch for user awareness.
4. Posting a comment in the Ironclad workflow’s activity feed with a link to the Jira issue for user awareness.
The following figure shows the steps that will be part of the Zapier rule. We'll now walk through the steps to configure this rule and make the necessary configuration changes in Jira and Ironclad.
<figure>
<img src="https://files.readme.io/1c73067-1._Workflow_Launch_-_Overview.png">
<figcaption><p>Zapier rule overview.</p></figcaption>
</figure>
## Configure Ironclad Workflow Fields
1. **In Ironclad**, prepare a workflow that includes three text fields in the launch form: (1) `Counterparty Name` (included out-of-the-box), (2) `Jira Issue ID`, and (3) `Cost Center`; these fields will be used to demonstrate how to pass data from Jira to Ironclad and also store the Jira issue’s unique ID so it can be referenced for later use.
You may add any other fields that you wish to populate with Jira information. For simplicity, we **strongly recommend** starting with the minimum number of fields (e.g., `Counterparty Name`, `Jira Issue ID`, and `Cost Center` fields) to verify that the integration works and adding additional fields afterwards.
<figure>
<img src="https://files.readme.io/7c06859-1._Launch_Workflow_-_Step_1.png">
<figcaption><p>Ironclad workflow launch form.</p></figcaption>
</figure>
2. **In Ironclad**, review the launch form and identify any required fields whose data cannot be supplied by Jira.
* Workflows created via API are automatically submitted; users do not fill in the launch form. As a result, any required fields on the launch form must be included in the API request.
* Note that internal user dropdowns are not supported in the Launch API at this time. Consider either (1) configuring any internal signer fields to use a group with a default user and updating the signer during the sign step when necessary or (2) moving the field to an internal form. See the [Launch a Workflow](doc:launch-a-workflow) guide for a comprehensive walkthrough of the endpoint, including complex data payloads and limitations.
* Convert any required fields whose information cannot be supplied to (1) [optional fields](https://support.ironcladapp.com/hc/en-us/articles/12403007165847-Customize-Form-Fields-in-Workflow-Designer) or (2) [internal form fields](https://support.ironcladapp.com/hc/en-us/articles/12250887031191-Form-Types-in-Workflow-Designer). **Note:** The Ironclad connector's launch workflow action treats all launch form fields as required at this time (including optional fields). Ironclad's underlying API does not have this restriction; you may wish to use a [raw Zapier webhook request](https://zapier.com/page/webhooks/) if you need to support an optional field.
3. **In Ironclad**, publish the workflow after completing the preceding steps.
## Configure Jira Issue Fields
4. **In Jira**, modify your issue to include the following text fields.
* `Vendor Name`
* `Cost Center`
* `Contract Requestor Email`
* `Ironclad Workflow ID`
* `Ironclad Workflow URL`
* `Ironclad Record ID`
* `Ironclad Record URL`
`Contract Requestor Email` will be required to launch the Ironclad workflow and the remaining fields will be used to store Ironclad data.
5. **In Jira**, create an automation rule to populate `Contract Requestor Email` using the reporter's information.
1. Click the **Gear icon () > System Settings > Automation Rules**.
2. Click **Create Rule** and select **Issue Created** as the trigger.
1. Name the rule `Add Contract Requestor Email`.
2. Add an **Edit Issue** action. Select *Contract Requestor Email* as the Jira field to update and enter `{{issue.reporter.emailAddress}}` as the value.
3. Enable and test the rule by creating a new issue to verify that `Contract Requestor Email` is populated.
> 🚧 Contract Requestor Email
>
> Please consider your company’s policy on allowing access to user email information. Jira limits availability of user information in its API. Creating a custom Jira field to populate it with the user’s email enables access to the information.
## Zapier - Configure Trigger
This section will configure a trigger to start our Zapier flow. We will create a webhook in Jira that will be sent after specific conditions are met in Jira. Our Zap will have a trigger that listens for the Jira webhook. This approach is used to illustrate the flexibility you have in determining when to launch an Ironclad workflow. If you have simple starting conditions, consider exploring the Jira triggers in Zapier which include triggers that start on issue creation.
6. **In Zapier**, create a new Zap. Add a **Webhook** trigger and select **Catch Hook** as the action event. Click **Continue** and copy the webhook URL generated by Zapier.
<figure>
<img src="https://files.readme.io/e6d4551-Screen_Shot_2021-12-03_at_2.40.01_PM.png">
<figcaption><p>Zapier trigger for catching webhook.</p></figcaption>
</figure>
7. **In Jira**, register a webhook that targets the Zapier URL from the preceding step.
1. Click the **Gear icon > System Settings > Webhooks > Create a Webhook**.
2. Customize the webhook to send only when the Jira issue moves to the right step in your process.
<figure>
<img src="https://files.readme.io/b412ad8-Screen_Shot_2021-12-03_at_2.47.17_PM.png">
<figcaption><p>This example triggers a webhook when there is a Jira update involving (1) a particular issue type, (2) an appropriate issue status transition, and (3) empty key fields. Condition (3) mitigates the possibility of Jira issues cycling between statuses and continually triggering workflows.</p></figcaption>
</figure>
8. **In Jira & Zapier**, test the webhook by triggering the webhook in Jira and clicking **Test Trigger** in Zapier to verify that the webhook has been received. Ensure that the Jira issue you use for your test includes data in the `Vendor Name`, `Cost Center`, and `Contract Requestor Email` fields; they will be used in the next section to map Jira fields to Ironclad fields.
## Zapier - Configure Workflow Launch
We are now ready to launch an Ironclad workflow with the Jira data we received from the section above.
9. **In Zapier**, add an **Ironclad** action and select **Launch New Workflow** as the event. Link your Ironclad environment by following the instructions to generate and provide an API token. This action will send a request to the [Create a Workflow Synchronously](ref:launch-a-new-workflow) endpoint to start a workflow.
1. For **Workflow Schema**, select the workflow design that you wish to launch.
2. Map Jira data to the Ironclad fields.
1. For **Email**, select the Jira field containing the `Contract Requestor Email` data. **Reminder:** The contract requestor must have an Ironclad user account and the Start Workflow permission for the workflow you wish to launch on their behalf.
2. For **Vendor Name** and **Cost Center**, select the `Vendor Name` and `Cost Center` Jira fields.
3. For **Jira Issue ID**, select the `Issue Key` field.
<figure>
<img src="https://files.readme.io/3ebf50b-1._Workflow_Launch_-_Step_9.png">
<figcaption><p>Launch Ironclad workflow configuration.</p></figcaption>
</figure>
## Zapier - Configure Jira Issue Update
It is important to store the Ironclad workflow ID after launch in Jira so it can be used by later integration steps and users. This step will update Jira with that information.
10. **In Zapier**, add an **Update Issue in Jira Software Cloud** action.
1. Click **Set Up Action > Issue (field) > Custom (tab)**. Select an issue.
<figure>
<img src="https://files.readme.io/1e363be-1._Launch_Workflow_-_Step_10a.png">
<figcaption><p>Select the attribute that holds the Jira issue ID.</p></figcaption>
</figure>
2. Configure the Jira field updates.
* For **Ironclad Workflow URL** and **Ironclad Workflow Id**, use the `ID` field from the response to the Launch New Workflow action.
* For **Reporter**, select the `Reporter Account Id` field from the trigger data.
* Update any other Jira fields as desired.
<figure>
<img src="https://files.readme.io/33b14ec-1._Launch_Workflow_-_Step_10b.png">
<figcaption><p>Add Jira field updates.</p></figcaption>
</figure>
3. Click **Continue** to save the configuration.
## Zapier - Configure Jira and Ironclad Comments
11. **In Zapier**, add an **Add Comment to Jira Issue** action to let users know that the Zapier automation has run. For **Issue**, select the `Issue Key` provided by the trigger.
<figure>
<img src="https://files.readme.io/f5ea3ed-1._Launch_Workflow_-_Step_11.png">
<figcaption><p>Add comment to Jira issue.</p></figcaption>
</figure>
12. **In Zapier**, add an **Ironclad** action and select **Create Workflow Comment in Ironclad** as the action event. The action will target the [Create a Comment on a Workflow](ref:create-a-comment-on-a-workflow) endpoint to add an activity feed comment to the Ironclad workflow.
1. For **Workflow ID**, select the `ID` property from the response to the Launch New Workflow action.
2. For **Email**, add a valid Ironclad user's email. The user will be attributed as the activity feed commenter so consider using a generic system user in Ironclad.
3. For **Comment**, add your preferred message such as a link back to the Jira issue for convenience.
<figure>
<img src="https://files.readme.io/b600674-1._Launch_Workflow_-_Step_12.png">
<figcaption><p>Add comment to Ironclad activity feed.</p></figcaption>
</figure>
13. **Publish your Zap**. Congratulations, you have a Zap that lets Jira business users start Ironclad workflows!Updated 18 days ago