How to Automate The Sharing of Promotion Codes

[#1]

codefortynine has recently introduced a new Partner Program for Solution Partners, including different partnership levels. As part of the program, Advanced Partners are eligible for a 10% discount, which needs to be requested individually for each quote.

This article explains how codefortynine automated the distribution of promotion codes in JSM for Solution Partners.

Once the request is completed and submitted, a promotion code will be automatically generated based on the provided information and sent directly to the Solution Partner with the help of our own app External Data for Jira Fields and a bit of Jira Automation magic.

If you are interested in setting up the same process, please follow the steps outlined below:

---

1. Create Search Field Where You Can Select The Promotion

Our first step on this journey is to get the Promotion data into Jira. In this case, we really need the Promotion ID to use it later in our automation to create the code via the API.

For that, we go to the External Data for Jira Fields configuration under Apps > External Data for Jira create a new Data Source. For Type, we select URL/REST. Then we enter the following URL to the GET endpoint from the Marketplace Promotions REST API, where we retrieve all of our promotions:

https://api.atlassian.com/marketplace/catalog/partners/{YOURPARTNERID}/promotions/paged?active-only=true&limit=1500

You will have to replace {YOURPARTNERID} with your current partner ID, which you can easily find by going to your Atlassian Marketplace Vendor page and copying the number in the URL after /vendors/. In the example of codefortynine the URL is https://marketplace.atlassian.com/vendors/1213041/codefortynine, so our Partner ID is 1213041.
For Authentication, we select Basic Auth and provide the email address and the API key of an Atlassian account that has access to your vendor page and to your promotions page.

Now you click Test and if everything is correct you should get a JSON response with all your active promotions.

Now we can create an Extension Search Field that uses our previously created Data Source.

First, we will create the target field by navigating to Available Jira Fields and clicking on + Add Custom Field, where we select External Data - Search Field. The field name should be rather descriptive, something like ‘Generate Promo Code’ to make it easy for users to see the purpose of the field.

Then we will create the field configuration under Field Configuration > + Add Extension Field > Search Field.

We will use a Context Filter to reduce the listed promotions only to relevant promotions for the individual Jira Service Management request. For the following expression, you will need a Jira custom field that contains the app name (or app key) of the app that is the request for:

$.promotions[?(@.eligibleApps[*].name=~/({$.issue.fields.customfield_XXXXX})/i)]

Then you can define all the paths for your field:

Most importantly, the ID field should be set to $.id so we can later retrieve the promotion ID in our automation.

Your Target Jira Field should be set to the custom field we just created and its Status active.

2. Automate The Creation of Promotion Codes

With the field from step 1 we can now automate the creation of new promotion codes from inside the request's agent view.

First, we create a custom field that will store the generated promotion codes. We go to Settings > Work items > Fields > Create new field and create a Labels field with a fitting name. We can also immediately search for the new field and check its field ID. Note that you can only see the ID if you checked the option to display it under Columns. You can copy or note down the ID for later use.

Now, we create a Jira Automation that uses the Marketplace Promotion REST API to create a new promotion code. We can trigger the automation if the custom field we use for our External Data Search Field is changed, and trigger it only if a value is added and if the custom field is not empty.

We then trigger a Send web request action. With the following configuration:

Web request URL	https://api.atlassian.com/marketplace/catalog/partners/1213041/promotions/{{issue.customfield_XXXXX.id}}/codes Replace {YOURPARTNERID} with your ID and XXXXX with the custom field ID of the field you use to store your promotion data from step 1
HTTP method	POST
Web request body	Empty
Headers	Key: Authorization Value: Basic EMAIL:APIKEY The EMAIL:APIKEY part needs to be Base64 encoded. You can generate the Base64 string using tools like https://www.base64encode.org/ or with command line tools: Linux/macOS: echo -n 'user@example.com:ABCD1234efgh5678' | base64 Windows PowerShell: [Convert]::ToBase64String(` [Text.Encoding]::UTF8.GetBytes('user@example.com:ABCD1234efgh5678')` )

Also, don’t forget to check the Delay execution […] option. Without it, you won’t be able to use the response in your further automation.

Lastly, we use the {{webResponse.body.code}} smart value to add the newly generated promotion code to the label field with an Edit work item action.

Now, agents can create new promotion codes for different apps in a Jira. If this is all you want you can stop here, but if you want to have the correct promotion code be generated automatically you need to continue to the next step.

3. Automatically Select The Correct Promotion

Before we can set the correct promotion automatically, you need to create a form for your partners where you can collect all the data needed and save it in custom fields to select the correct promotion. This should include at least the following:

• App Name

• Hosting Type (CLOUD/DATA CENTER)

• Subscription Type (ANNUAL/MONTHLY)

• For how many billing cycles? (Number)

Feel free to check our own form for reference.

Now, can we use an External Data for Jira Fields Dependant field to set the correct promotion. We set the Data Source to the one we set up in step 1 and use the following context filter:

$.promotions[?(@.eligibleApps[*].name=~/({$.issue.fields.customfield_XXXXX.value})/i && @.hostingType=~/({$.issue.fields.customfield_XXXXX.value})/i && @.subscriptionType=~/({$.issue.fields.customfield_XXXXX.value})/i && @.allowedBillingCycles=={$.issue.fields.customfield_XXXXX.value}

You need to replace the custom field IDs in the context filter with the IDs of the fields you used to store the responses of your Jira Service Management form. You also might want to add more conditions to the filter if you have multiple promotions that fit the other conditions. We use the additional filter @.name=~/(XXX)/) and give a unique string to promotions reserved for our partners.

For the other fields, use the following options:

Value Type	Extension Search
ID Field	$.id
Value Field	$.name
Empty Behaviour	Do nothing
Target Jira Field	Select the field you created in step 1
Update Condition	Only if target Jira field is empty

This will make it, so the correct promotion will be selected for the field, and your Jira automation from step 2 will create a new promotion code. Now you can either send the code manually or also automate this step and quickly provide your partners with the requested codes.

---

Let us know what you think in the comments, and feel free to contact us if you want to join our Partner Program.